Threads

## Threads Threads — portable support for threads, mutexes, locks, conditions and thread private data |

## Functions

gpointer | (*GThreadFunc) ()
GThread * | g_thread_new ()
GThread * | g_thread_try_new ()
GThread * | g_thread_ref ()
void | g_thread_unref ()
gpointer | g_thread_join ()
void | g_thread_yield ()
void | g_thread_exit ()
GThread * | g_thread_self ()
void | g_mutex_init ()
void | g_mutex_clear ()
void | g_mutex_lock ()
gboolean | g_mutex_trylock ()
void | g_mutex_unlock ()
GMutexLocker * | g_mutex_locker_new ()
void | g_mutex_locker_free ()
#define | G_LOCK_DEFINE()
#define | G_LOCK_DEFINE_STATIC()
#define | G_LOCK_EXTERN()
#define | G_LOCK()
#define | G_TRYLOCK()
#define | G_UNLOCK()
void | g_rec_mutex_init ()
void | g_rec_mutex_clear ()
void | g_rec_mutex_lock ()
gboolean | g_rec_mutex_trylock ()
void | g_rec_mutex_unlock ()
void | g_rw_lock_init ()
void | g_rw_lock_clear ()
void | g_rw_lock_writer_lock ()
gboolean | g_rw_lock_writer_trylock ()
void | g_rw_lock_writer_unlock ()
void | g_rw_lock_reader_lock ()
gboolean | g_rw_lock_reader_trylock ()
void | g_rw_lock_reader_unlock ()
void | g_cond_init ()
void | g_cond_clear ()
void | g_cond_wait ()
gboolean | g_cond_timed_wait ()
gboolean | g_cond_wait_until ()
void | g_cond_signal ()
void | g_cond_broadcast ()
#define | G_PRIVATE_INIT()
gpointer | g_private_get ()
void | g_private_set ()
void | g_private_replace ()
#define | g_once()
gboolean | g_once_init_enter ()
void | g_once_init_leave ()
void | g_bit_lock ()
gboolean | g_bit_trylock ()
void | g_bit_unlock ()
void | g_pointer_bit_lock ()
gboolean | g_pointer_bit_trylock ()
void | g_pointer_bit_unlock ()
guint | g_get_num_processors ()

## Types and Values

#define | G_THREAD_ERROR
enum | GThreadError
| GThread
union | GMutex
typedef | GMutexLocker
struct | GRecMutex
struct | GRWLock
struct | GCond
struct | GPrivate
struct | GOnce
enum | GOnceStatus
#define | G_ONCE_INIT

## Includes

    #include <glib.h>

## Description

Threads act almost like processes, but unlike processes all threads of one process share the same memory. This is good, as it provides easy communication between the involved threads via this shared memory, and it is bad, because strange things (so called "Heisenbugs") might happen if the program is not carefully designed. In particular, due to the concurrent nature of threads, no assumptions on the order of execution of code running in different threads can be made, unless order is explicitly forced by the programmer through synchronization primitives.

The aim of the thread-related functions in GLib is to provide a portable means for writing multi-threaded software. There are primitives for mutexes to protect the access to portions of memory (GMutex, GRecMutex and GRWLock). There is a facility to use individual bits for locks (`g_bit_lock()`). There are primitives for condition variables to allow synchronization of threads (GCond). There are primitives for thread-private data - data that every thread has a private instance of (GPrivate). There are facilities for one-time initialization (GOnce, `g_once_init_enter()`). Finally, there are primitives to create and manage threads (GThread).

The GLib threading system used to be initialized with `g_thread_init()`. This is no longer necessary. Since version 2.32, the GLib threading system is automatically initialized at the start of your program, and all thread-creation functions and synchronization primitives are available right away.

Note that it is not safe to assume that your program has no threads even if you don't call `g_thread_new()` yourself. GLib and GIO can and will create threads for their own purposes in some cases, such as when using `g_unix_signal_source_new()` or when using GDBus.

Originally, UNIX did not have threads, and therefore some traditional UNIX APIs are problematic in threaded programs. Some notable examples are

- C library functions that return data in statically allocated buffers, such as `strtok()` or `strerror()`. For many of these, there are thread-safe variants with a _r suffix, or you can look at corresponding GLib APIs (like `g_strsplit()` or `g_strerror()`).

- The functions `setenv()` and `unsetenv()` manipulate the process environment in a not thread-safe way, and may interfere with `getenv()` calls in other threads. Note that `getenv()` calls may be hidden behind other APIs. For example, GNU `gettext()` calls `getenv()` under the covers. In general, it is best to treat the environment as readonly. If you absolutely have to modify the environment, do it early in `main()`, when no other threads are around yet.

- The `setlocale()` function changes the locale for the entire process, affecting all threads. Temporary changes to the locale are often made to change the behavior of string scanning or formatting functions like `scanf()` or `printf()`. GLib offers a number of string APIs (like `g_ascii_formatd()` or `g_ascii_strtod()`) that can often be used as an alternative. Or you can use the `uselocale()` function to change the locale only for the current thread.

- The `fork()` function only takes the calling thread into the child's copy of the process image. If other threads were executing in critical sections they could have left mutexes locked which could easily cause deadlocks in the new child. For this reason, you should call `exit()` or `exec()` as soon as possible in the child and only make signal-safe library calls before that.

- The `daemon()` function uses `fork()` in a way contrary to what is described above. It should not be used with GLib programs.

GLib itself is internally completely thread-safe (all global data is automatically locked), but individual data structure instances are not automatically locked for performance reasons. For example, you must coordinate accesses to the same GHashTable from multiple threads. The two notable exceptions from this rule are GMainLoop and GAsyncQueue, which are thread-safe and need no further application-level locking to be accessed from multiple threads. Most refcounting functions such as `g_object_ref()` are also thread-safe.

A common use for GThreads is to move a long-running blocking operation out of the main thread and into a worker thread. For GLib functions, such as single GIO operations, this is not necessary, and complicates the code. Instead, the `…`_async()`` version of the function should be used from the main thread, eliminating the need for locking and synchronisation between multiple threads. If an operation does need to be moved to a worker thread, consider using `g_task_run_in_thread()`, or a GThreadPool. GThreadPool is often a better choice than GThread, as it handles thread reuse and task queueing; GTask uses this internally.

However, if multiple blocking operations need to be performed in sequence, and it is not possible to use GTask for them, moving them to a worker thread can clarify the code.

## Functions

### GThreadFunc ()

    gpointer
    (*GThreadFunc) (gpointer data);

Specifies the type of the `func` functions passed to `g_thread_new()` or `g_thread_try_new()`.

#### Parameters

data | data passed to the thread |

#### Returns

the return value of the thread

### g_thread_new ()

    GThread *
    g_thread_new (const gchar *name,
                  GThreadFunc func,
                  gpointer data);

This function creates a new thread. The new thread starts by invoking `func` with the argument data. The thread will run until `func` returns or until `g_thread_exit()` is called from the new thread. The return value of `func` becomes the return value of the thread, which can be obtained with `g_thread_join()`.

The `name` can be useful for discriminating threads in a debugger. It is not used for other purposes and does not have to be unique. Some systems restrict the length of `name` to 16 bytes.

If the thread can not be created the program aborts. See `g_thread_try_new()` if you want to attempt to deal with failures.

If you are using threads to offload (potentially many) short-lived tasks, GThreadPool may be more appropriate than manually spawning and tracking multiple GThreads.

To free the struct returned by this function, use `g_thread_unref()`. Note that `g_thread_join()` implicitly unrefs the GThread as well.

#### Parameters

name | an (optional) name for the new thread. | [allow-none]
func | a function to execute in the new thread |
data | an argument to supply to the new thread |

#### Returns

the new GThread

Since: 2.32

### g_thread_try_new ()

    GThread *
    g_thread_try_new (const gchar *name,
                      GThreadFunc func,
                      gpointer data,
                      GError **error);

This function is the same as `g_thread_new()` except that it allows for the possibility of failure.

If a thread can not be created (due to resource limits), `error` is set and `NULL` is returned.

#### Parameters

name | an (optional) name for the new thread. | [allow-none]
func | a function to execute in the new thread |
data | an argument to supply to the new thread |
error | return location for error, or `NULL` |

#### Returns

the new GThread, or `NULL` if an error occurred

Since: 2.32

### g_thread_ref ()

    GThread *
    g_thread_ref (GThread *thread);

Increase the reference count on `thread` .

#### Parameters

thread | a GThread |

#### Returns

a new reference to `thread`

Since: 2.32

### g_thread_unref ()

    void
    g_thread_unref (GThread *thread);

Decrease the reference count on `thread` , possibly freeing all resources associated with it.

Note that each thread holds a reference to its GThread while it is running, so it is safe to drop your own reference to it if you don't need it anymore.

#### Parameters

thread | a GThread |

Since: 2.32

### g_thread_join ()

    gpointer
    g_thread_join (GThread *thread);

Waits until `thread` finishes, i.e. the function `func` , as given to `g_thread_new()`, returns or `g_thread_exit()` is called. If `thread` has already terminated, then `g_thread_join()` returns immediately.

Any thread can wait for any other thread by calling `g_thread_join()`, not just its 'creator'. Calling `g_thread_join()` from multiple threads for the same `thread` leads to undefined behaviour.

The value returned by `func` or given to `g_thread_exit()` is returned by this function.

g_thread_join() consumes the reference to the passed-in `thread` . This will usually cause the GThread struct and associated resources to be freed. Use `g_thread_ref()` to obtain an extra reference if you want to keep the GThread alive beyond the `g_thread_join()` call.

#### Parameters

thread | a GThread |

#### Returns

the return value of the thread

### g_thread_yield ()

    void
    g_thread_yield ();

Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run.

This function is often used as a method to make busy wait less evil.

### g_thread_exit ()

    void
    g_thread_exit (gpointer retval);

Terminates the current thread.

If another thread is waiting for us using `g_thread_join()` then the waiting thread will be woken up and get `retval` as the return value of `g_thread_join()`.

Calling `g_thread_exit()` with a parameter `retval` is equivalent to returning `retval` from the function `func` , as given to `g_thread_new()`.

You must only call `g_thread_exit()` from a thread that you created yourself with `g_thread_new()` or related APIs. You must not call this function from a thread created with another threading library or or from within a GThreadPool.

#### Parameters

retval | the return value of this thread |

### g_thread_self ()

    GThread *
    g_thread_self (void);

This function returns the GThread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct.

This function will return a GThread even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as `g_thread_join()`) on these threads.

#### Returns

the GThread representing the current thread

### g_mutex_init ()

    void
    g_mutex_init (GMutex *mutex);

Initializes a GMutex so that it can be used.

This function is useful to initialize a mutex that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialize a mutex that has been statically allocated.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    typedef struct {
      GMutex m;
      ...
    } Blob;

    Blob *b;

    b = g_new (Blob, 1);
    g_mutex_init (&b->m);

To undo the effect of `g_mutex_init()` when a mutex is no longer needed, use `g_mutex_clear()`.

Calling `g_mutex_init()` on an already initialized GMutex leads to undefined behaviour.

#### Parameters

mutex | an uninitialized GMutex |

Since: 2.32

### g_mutex_clear ()

    void
    g_mutex_clear (GMutex *mutex);

Frees the resources allocated to a mutex with `g_mutex_init()`.

This function should not be used with a GMutex that has been statically allocated.

Calling `g_mutex_clear()` on a locked mutex leads to undefined behaviour.

Sine: 2.32

#### Parameters

mutex | an initialized GMutex |

### g_mutex_lock ()

    void
    g_mutex_lock (GMutex *mutex);

Locks `mutex` . If `mutex` is already locked by another thread, the current thread will block until `mutex` is unlocked by the other thread.

GMutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling `g_mutex_lock()` on a GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks).

#### Parameters

mutex | a GMutex |

### g_mutex_trylock ()

    gboolean
    g_mutex_trylock (GMutex *mutex);

Tries to lock `mutex` . If `mutex` is already locked by another thread, it immediately returns `FALSE`. Otherwise it locks `mutex` and returns `TRUE`.

GMutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling `g_mutex_lock()` on a GMutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks or arbitrary return values).

#### Parameters

mutex | a GMutex |

#### Returns

`TRUE` if `mutex` could be locked

### g_mutex_unlock ()

    void
    g_mutex_unlock (GMutex *mutex);

Unlocks `mutex` . If another thread is blocked in a `g_mutex_lock()` call for `mutex` , it will become unblocked and can lock `mutex` itself.

Calling `g_mutex_unlock()` on a mutex that is not locked by the current thread leads to undefined behaviour.

#### Parameters

mutex | a GMutex |

### g_mutex_locker_new ()

    GMutexLocker *
    g_mutex_locker_new (GMutex *mutex);

Lock `mutex` and return a new GMutexLocker. Unlock with `g_mutex_locker_free()`. Using `g_mutex_unlock()` on `mutex` while a GMutexLocker exists can lead to undefined behaviour.

This is intended to be used with `g_autoptr()`. Note that `g_autoptr()` is only available when using GCC or clang, so the following example will only work with those compilers:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    typedef struct
    {
      ...
      GMutex mutex;
      ...
    } MyObject;

    static void
    my_object_do_stuff (MyObject *self)
    {
      g_autoptr(GMutexLocker) locker = g_mutex_locker_new (&self->mutex);

      // Code with mutex locked here

      if (cond)
        // No need to unlock
        return;

      // Optionally early unlock
      g_clear_pointer (&locker, g_mutex_locker_free);

      // Code with mutex unlocked here
    }

#### Parameters

mutex | a mutex to lock |

#### Returns

a GMutexLocker

Since: 2.44

### g_mutex_locker_free ()

    void
    g_mutex_locker_free (GMutexLocker *locker);

Unlock `locker` 's mutex. See `g_mutex_locker_new()` for details.

#### Parameters

locker | a GMutexLocker |

Since: 2.44

### G_LOCK_DEFINE()

    #define G_LOCK_DEFINE(name)

The G_LOCK_ macros provide a convenient interface to GMutex. G_LOCK_DEFINE defines a lock. It can appear in any place where variable definitions may appear in programs, i.e. in the first block of a function or outside of functions. The `name` parameter will be mangled to get the name of the GMutex. This means that you can use names of existing variables as the parameter - e.g. the name of the variable you intend to protect with the lock. Look at our `give_me_next_number()` example using the G_LOCK macros:

Here is an example for using the G_LOCK convenience macros:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    G_LOCK_DEFINE (current_number);

    int
    give_me_next_number (void)
    {
      static int current_number = 0;
      int ret_val;

      G_LOCK (current_number);
      ret_val = current_number = calc_next_number (current_number);
      G_UNLOCK (current_number);

      return ret_val;
    }

#### Parameters

name | the name of the lock |

### G_LOCK_DEFINE_STATIC()

    #define G_LOCK_DEFINE_STATIC(name)

This works like G_LOCK_DEFINE, but it creates a static object.

#### Parameters

name | the name of the lock |

### G_LOCK_EXTERN()

    #define G_LOCK_EXTERN(name)

This declares a lock, that is defined with G_LOCK_DEFINE in another module.

#### Parameters

name | the name of the lock |

### G_LOCK()

    #define G_LOCK(name)

Works like `g_mutex_lock()`, but for a lock defined with G_LOCK_DEFINE.

#### Parameters

name | the name of the lock |

### G_TRYLOCK()

    #define G_TRYLOCK(name)

Works like `g_mutex_trylock()`, but for a lock defined with G_LOCK_DEFINE.

#### Parameters

name | the name of the lock |

#### Returns

`TRUE`, if the lock could be locked.

### G_UNLOCK()

    #define G_UNLOCK(name)

Works like `g_mutex_unlock()`, but for a lock defined with G_LOCK_DEFINE.

#### Parameters

name | the name of the lock |

### g_rec_mutex_init ()

    void
    g_rec_mutex_init (GRecMutex *rec_mutex);

Initializes a GRecMutex so that it can be used.

This function is useful to initialize a recursive mutex that has been allocated on the stack, or as part of a larger structure.

It is not necessary to initialise a recursive mutex that has been statically allocated.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    typedef struct {
      GRecMutex m;
      ...
    } Blob;

    Blob *b;

    b = g_new (Blob, 1);
    g_rec_mutex_init (&b->m);

Calling `g_rec_mutex_init()` on an already initialized GRecMutex leads to undefined behaviour.

To undo the effect of `g_rec_mutex_init()` when a recursive mutex is no longer needed, use `g_rec_mutex_clear()`.

#### Parameters

rec_mutex | an uninitialized GRecMutex |

Since: 2.32

### g_rec_mutex_clear ()

    void
    g_rec_mutex_clear (GRecMutex *rec_mutex);

Frees the resources allocated to a recursive mutex with `g_rec_mutex_init()`.

This function should not be used with a GRecMutex that has been statically allocated.

Calling `g_rec_mutex_clear()` on a locked recursive mutex leads to undefined behaviour.

Sine: 2.32

#### Parameters

rec_mutex | an initialized GRecMutex |

### g_rec_mutex_lock ()

    void
    g_rec_mutex_lock (GRecMutex *rec_mutex);

Locks `rec_mutex` . If `rec_mutex` is already locked by another thread, the current thread will block until `rec_mutex` is unlocked by the other thread. If `rec_mutex` is already locked by the current thread, the 'lock count' of `rec_mutex` is increased. The mutex will only become available again when it is unlocked as many times as it has been locked.

#### Parameters

rec_mutex | a GRecMutex |

Since: 2.32

### g_rec_mutex_trylock ()

    gboolean
    g_rec_mutex_trylock (GRecMutex *rec_mutex);

Tries to lock `rec_mutex` . If `rec_mutex` is already locked by another thread, it immediately returns `FALSE`. Otherwise it locks `rec_mutex` and returns `TRUE`.

#### Parameters

rec_mutex | a GRecMutex |

#### Returns

`TRUE` if `rec_mutex` could be locked

Since: 2.32

### g_rec_mutex_unlock ()

    void
    g_rec_mutex_unlock (GRecMutex *rec_mutex);

Unlocks `rec_mutex` . If another thread is blocked in a `g_rec_mutex_lock()` call for `rec_mutex` , it will become unblocked and can lock `rec_mutex` itself.

Calling `g_rec_mutex_unlock()` on a recursive mutex that is not locked by the current thread leads to undefined behaviour.

#### Parameters

rec_mutex | a GRecMutex |

Since: 2.32

### g_rw_lock_init ()

    void
    g_rw_lock_init (GRWLock *rw_lock);

Initializes a GRWLock so that it can be used.

This function is useful to initialize a lock that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialise a reader-writer lock that has been statically allocated.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    typedef struct {
      GRWLock l;
      ...
    } Blob;

    Blob *b;

    b = g_new (Blob, 1);
    g_rw_lock_init (&b->l);

To undo the effect of `g_rw_lock_init()` when a lock is no longer needed, use `g_rw_lock_clear()`.

Calling `g_rw_lock_init()` on an already initialized GRWLock leads to undefined behaviour.

#### Parameters

rw_lock | an uninitialized GRWLock |

Since: 2.32

### g_rw_lock_clear ()

    void
    g_rw_lock_clear (GRWLock *rw_lock);

Frees the resources allocated to a lock with `g_rw_lock_init()`.

This function should not be used with a GRWLock that has been statically allocated.

Calling `g_rw_lock_clear()` when any thread holds the lock leads to undefined behaviour.

Sine: 2.32

#### Parameters

rw_lock | an initialized GRWLock |

### g_rw_lock_writer_lock ()

    void
    g_rw_lock_writer_lock (GRWLock *rw_lock);

Obtain a write lock on `rw_lock` . If any thread already holds a read or write lock on `rw_lock` , the current thread will block until all other threads have dropped their locks on `rw_lock` .

#### Parameters

rw_lock | a GRWLock |

Since: 2.32

### g_rw_lock_writer_trylock ()

    gboolean
    g_rw_lock_writer_trylock (GRWLock *rw_lock);

Tries to obtain a write lock on `rw_lock` . If any other thread holds a read or write lock on `rw_lock` , it immediately returns `FALSE`. Otherwise it locks `rw_lock` and returns `TRUE`.

#### Parameters

rw_lock | a GRWLock |

#### Returns

`TRUE` if `rw_lock` could be locked

Since: 2.32

### g_rw_lock_writer_unlock ()

    void
    g_rw_lock_writer_unlock (GRWLock *rw_lock);

Release a write lock on `rw_lock` .

Calling `g_rw_lock_writer_unlock()` on a lock that is not held by the current thread leads to undefined behaviour.

#### Parameters

rw_lock | a GRWLock |

Since: 2.32

### g_rw_lock_reader_lock ()

    void
    g_rw_lock_reader_lock (GRWLock *rw_lock);

Obtain a read lock on `rw_lock` . If another thread currently holds the write lock on `rw_lock` or blocks waiting for it, the current thread will block. Read locks can be taken recursively.

It is implementation-defined how many threads are allowed to hold read locks on the same lock simultaneously.

#### Parameters

rw_lock | a GRWLock |

Since: 2.32

### g_rw_lock_reader_trylock ()

    gboolean
    g_rw_lock_reader_trylock (GRWLock *rw_lock);

Tries to obtain a read lock on `rw_lock` and returns `TRUE` if the read lock was successfully obtained. Otherwise it returns `FALSE`.

#### Parameters

rw_lock | a GRWLock |

#### Returns

`TRUE` if `rw_lock` could be locked

Since: 2.32

### g_rw_lock_reader_unlock ()

    void
    g_rw_lock_reader_unlock (GRWLock *rw_lock);

Release a read lock on `rw_lock` .

Calling `g_rw_lock_reader_unlock()` on a lock that is not held by the current thread leads to undefined behaviour.

#### Parameters

rw_lock | a GRWLock |

Since: 2.32

### g_cond_init ()

    void
    g_cond_init (GCond *cond);

Initialises a GCond so that it can be used.

This function is useful to initialise a GCond that has been allocated as part of a larger structure. It is not necessary to initialise a GCond that has been statically allocated.

To undo the effect of `g_cond_init()` when a GCond is no longer needed, use `g_cond_clear()`.

Calling `g_cond_init()` on an already-initialised GCond leads to undefined behaviour.

#### Parameters

cond | an uninitialized GCond |

Since: 2.32

### g_cond_clear ()

    void
    g_cond_clear (GCond *cond);

Frees the resources allocated to a GCond with `g_cond_init()`.

This function should not be used with a GCond that has been statically allocated.

Calling `g_cond_clear()` for a GCond on which threads are blocking leads to undefined behaviour.

#### Parameters

cond | an initialised GCond |

Since: 2.32

### g_cond_wait ()

    void
    g_cond_wait (GCond *cond,
                 GMutex *mutex);

Atomically releases `mutex` and waits until `cond` is signalled. When this function returns, `mutex` is locked again and owned by the calling thread.

When using condition variables, it is possible that a spurious wakeup may occur (ie: `g_cond_wait()` returns even though `g_cond_signal()` was not called). It's also possible that a stolen wakeup may occur. This is when `g_cond_signal()` is called, but another thread acquires `mutex` before this thread and modifies the state of the program in such a way that when `g_cond_wait()` is able to return, the expected condition is no longer met.

For this reason, `g_cond_wait()` must always be used in a loop. See the documentation for GCond for a complete example.

#### Parameters

cond | a GCond |
mutex | a GMutex that is currently locked |

### g_cond_timed_wait ()

    gboolean
    g_cond_timed_wait (GCond *cond,
                       GMutex *mutex,
                       GTimeVal *abs_time);

`g_cond_timed_wait` has been deprecated since version 2.32 and should not be used in newly-written code.

Use `g_cond_wait_until()` instead.

Waits until this thread is woken up on `cond` , but not longer than until the time specified by `abs_time` . The `mutex` is unlocked before falling asleep and locked again before resuming.

If `abs_time` is `NULL`, `g_cond_timed_wait()` acts like `g_cond_wait()`.

This function can be used even if `g_thread_init()` has not yet been called, and, in that case, will immediately return `TRUE`.

To easily calculate `abs_time` a combination of `g_get_current_time()` and `g_time_val_add()` can be used.

#### Parameters

cond | a GCond |
mutex | a GMutex that is currently locked |
abs_time | a GTimeVal, determining the final time |

#### Returns

`TRUE` if `cond` was signalled, or `FALSE` on timeout

### g_cond_wait_until ()

    gboolean
    g_cond_wait_until (GCond *cond,
                       GMutex *mutex,
                       gint64 end_time);

Waits until either `cond` is signalled or `end_time` has passed.

As with `g_cond_wait()` it is possible that a spurious or stolen wakeup could occur. For that reason, waiting on a condition variable should always be in a loop, based on an explicitly-checked predicate.

`TRUE` is returned if the condition variable was signalled (or in the case of a spurious wakeup). `FALSE` is returned if `end_time` has passed.

The following code shows how to correctly perform a timed wait on a condition variable (extending the example presented in the documentation for GCond):

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    gpointer
    pop_data_timed (void)
    {
      gint64 end_time;
      gpointer data;

      g_mutex_lock (&data_mutex);

      end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
      while (!current_data)
        if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
          {
            // timeout has passed.
            g_mutex_unlock (&data_mutex);
            return NULL;
          }

      // there is data for us
      data = current_data;
      current_data = NULL;

      g_mutex_unlock (&data_mutex);

      return data;
    }

Notice that the end time is calculated once, before entering the loop and reused. This is the motivation behind the use of absolute time on this API -- if a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again (which would lead to a total wait time of more than 5 seconds).

#### Parameters

cond | a GCond |
mutex | a GMutex that is currently locked |
end_time | the monotonic time to wait until |

#### Returns

`TRUE` on a signal, `FALSE` on a timeout

Since: 2.32

### g_cond_signal ()

    void
    g_cond_signal (GCond *cond);

If threads are waiting for `cond` , at least one of them is unblocked. If no threads are waiting for `cond` , this function has no effect. It is good practice to hold the same lock as the waiting thread while calling this function, though not required.

#### Parameters

cond | a GCond |

### g_cond_broadcast ()

    void
    g_cond_broadcast (GCond *cond);

If threads are waiting for `cond` , all of them are unblocked. If no threads are waiting for `cond` , this function has no effect. It is good practice to lock the same mutex as the waiting threads while calling this function, though not required.

#### Parameters

cond | a GCond |

### G_PRIVATE_INIT()

    #define G_PRIVATE_INIT(notify)

A macro to assist with the static initialisation of a GPrivate.

This macro is useful for the case that a GDestroyNotify function should be associated the key. This is needed when the key will be used to point at memory that should be deallocated when the thread exits.

Additionally, the GDestroyNotify will also be called on the previous value stored in the key when `g_private_replace()` is used.

If no GDestroyNotify is needed, then use of this macro is not required -- if the GPrivate is declared in static scope then it will be properly initialised by default (ie: to all zeros). See the examples below.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    static GPrivate name_key = G_PRIVATE_INIT (g_free);

    // return value should not be freed
    const gchar *
    get_local_name (void)
    {
      return g_private_get (&name_key);
    }

    void
    set_local_name (const gchar *name)
    {
      g_private_replace (&name_key, g_strdup (name));
    }

    static GPrivate count_key;   // no free function

    gint
    get_local_count (void)
    {
      return GPOINTER_TO_INT (g_private_get (&count_key));
    }

    void
    set_local_count (gint count)
    {
      g_private_set (&count_key, GINT_TO_POINTER (count));
    }

#### Parameters

notify | a GDestroyNotify |

Since: 2.32

### g_private_get ()

    gpointer
    g_private_get (GPrivate *key);

Returns the current value of the thread local variable `key` .

If the value has not yet been set in this thread, `NULL` is returned. Values are never copied between threads (when a new thread is created, for example).

#### Parameters

key | a GPrivate |

#### Returns

the thread-local value

### g_private_set ()

    void
    g_private_set (GPrivate *key,
                   gpointer value);

Sets the thread local variable `key` to have the value `value` in the current thread.

This function differs from `g_private_replace()` in the following way: the GDestroyNotify for `key` is not called on the old value.

#### Parameters

key | a GPrivate |
value | the new value |

### g_private_replace ()

    void
    g_private_replace (GPrivate *key,
                       gpointer value);

Sets the thread local variable `key` to have the value `value` in the current thread.

This function differs from `g_private_set()` in the following way: if the previous value was non-`NULL` then the GDestroyNotify handler for `key` is run on it.

#### Parameters

key | a GPrivate |
value | the new value |

Since: 2.32

### g_once()

    #define             g_once(once, func, arg)

The first call to this routine by a process with a given GOnce struct calls `func` with the given argument. Thereafter, subsequent calls to `g_once()` with the same GOnce struct do not call `func` again, but return the stored result of the first call. On return from `g_once()`, the status of `once` will be `G_ONCE_STATUS_READY`.

For example, a mutex or a thread-specific data key must be created exactly once. In a threaded environment, calling `g_once()` ensures that the initialization is serialized across multiple threads.

Calling `g_once()` recursively on the same GOnce struct in `func` will lead to a deadlock.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    gpointer
    get_debug_flags (void)
    {
      static GOnce my_once = G_ONCE_INIT;

      g_once (&my_once, parse_debug_flags, NULL);

      return my_once.retval;
    }

#### Parameters

once | a GOnce structure |
func | the GThreadFunc function associated to `once` . This function is called only once, regardless of the number of times it and its associated GOnce struct are passed to `g_once()`. |
arg | data to be passed to `func` |

Since: 2.4

### g_once_init_enter ()

    gboolean
    g_once_init_enter (volatile void *location);

Function to be called when starting a critical initialization section. The argument `location` must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with `g_once_init_leave()` and the unique address `value_location` , it can be ensured that an initialization section will be executed only once during a program's life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    static gsize initialization_value = 0;

    if (g_once_init_enter (&initialization_value))
      {
        gsize setup_value = 42; // initialization code here

        g_once_init_leave (&initialization_value, setup_value);
      }

    // use initialization_value here

#### Parameters

location | location of a static initializable variable containing 0 |

#### Returns

`TRUE` if the initialization section should be entered, `FALSE` and blocks otherwise

Since: 2.14

### g_once_init_leave ()

    void
    g_once_init_leave (volatile void *location,
                       gsize result);

Counterpart to `g_once_init_enter()`. Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in `g_once_init_enter()` on this initialization variable.

#### Parameters

location | location of a static initializable variable containing 0 |
result | new non-0 value for *`value_location` |

Since: 2.14

### g_bit_lock ()

    void
    g_bit_lock (volatile gint *address,
                gint lock_bit);

Sets the indicated `lock_bit` in `address` . If the bit is already set, this call will block until `g_bit_unlock()` unsets the corresponding bit.

Attempting to lock on two different bits within the same integer is not supported and will very probably cause deadlocks.

The value of the bit that is set is (1u << `bit` ). If `bit` is not between 0 and 31 then the result is undefined.

This function accesses `address` atomically. All other accesses to `address` must be atomic in order for this function to work reliably.

#### Parameters

address | a pointer to an integer |
lock_bit | a bit value between 0 and 31 |

Since: 2.24

### g_bit_trylock ()

    gboolean
    g_bit_trylock (volatile gint *address,
                   gint lock_bit);

Sets the indicated `lock_bit` in `address` , returning `TRUE` if successful. If the bit is already set, returns `FALSE` immediately.

Attempting to lock on two different bits within the same integer is not supported.

The value of the bit that is set is (1u << `bit` ). If `bit` is not between 0 and 31 then the result is undefined.

This function accesses `address` atomically. All other accesses to `address` must be atomic in order for this function to work reliably.

#### Parameters

address | a pointer to an integer |
lock_bit | a bit value between 0 and 31 |

#### Returns

`TRUE` if the lock was acquired

Since: 2.24

### g_bit_unlock ()

    void
    g_bit_unlock (volatile gint *address,
                  gint lock_bit);

Clears the indicated `lock_bit` in `address` . If another thread is currently blocked in `g_bit_lock()` on this same bit then it will be woken up.

This function accesses `address` atomically. All other accesses to `address` must be atomic in order for this function to work reliably.

#### Parameters

address | a pointer to an integer |
lock_bit | a bit value between 0 and 31 |

Since: 2.24

### g_pointer_bit_lock ()

    void
    g_pointer_bit_lock (volatile void *address,
                        gint lock_bit);

This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values).

For portability reasons, you may only lock on the bottom 32 bits of the pointer.

#### Parameters

address | a pointer to a gpointer-sized value |
lock_bit | a bit value between 0 and 31 |

Since: 2.30

### g_pointer_bit_trylock ()

    gboolean
    g_pointer_bit_trylock (volatile void *address,
                           gint lock_bit);

This is equivalent to g_bit_trylock, but working on pointers (or other pointer-sized values).

For portability reasons, you may only lock on the bottom 32 bits of the pointer.

#### Parameters

address | a pointer to a gpointer-sized value |
lock_bit | a bit value between 0 and 31 |

#### Returns

`TRUE` if the lock was acquired

Since: 2.30

### g_pointer_bit_unlock ()

    void
    g_pointer_bit_unlock (volatile void *address,
                          gint lock_bit);

This is equivalent to g_bit_unlock, but working on pointers (or other pointer-sized values).

For portability reasons, you may only lock on the bottom 32 bits of the pointer.

#### Parameters

address | a pointer to a gpointer-sized value |
lock_bit | a bit value between 0 and 31 |

Since: 2.30

### g_get_num_processors ()

    guint
    g_get_num_processors (void);

Determine the approximate number of threads that the system will schedule simultaneously for this process. This is intended to be used as a parameter to `g_thread_pool_new()` for CPU bound tasks and similar cases.

#### Returns

Number of schedulable threads, always greater than 0

Since: 2.36

## Types and Values

### G_THREAD_ERROR

    #define G_THREAD_ERROR g_thread_error_quark ()

The error domain of the GLib thread subsystem.

### enum GThreadError

Possible errors of thread related functions.

#### Members

G_THREAD_ERROR_AGAIN | a thread couldn't be created due to resource shortage. Try again later. |

### GThread

    typedef struct {
    } GThread;

The GThread struct represents a running thread. This struct is returned by `g_thread_new()` or `g_thread_try_new()`. You can obtain the GThread struct representing the current thread by calling `g_thread_self()`.

GThread is refcounted, see `g_thread_ref()` and `g_thread_unref()`. The thread represented by it holds a reference while it is running, and `g_thread_join()` consumes the reference that it is given, so it is normally not necessary to manage GThread references explicitly.

The structure is opaque -- none of its fields may be directly accessed.

### union GMutex

The GMutex struct is an opaque data structure to represent a mutex (mutual exclusion). It can be used to protect data against shared access.

Take for example the following function:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    int
    give_me_next_number (void)
    {
      static int current_number = 0;

      // now do a very complicated calculation to calculate the new
      // number, this might for example be a random number generator
      current_number = calc_next_number (current_number);

      return current_number;
    }

It is easy to see that this won't work in a multi-threaded application. There current_number must be protected against shared access. A GMutex can be used as a solution to this problem:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    int
    give_me_next_number (void)
    {
      static GMutex mutex;
      static int current_number = 0;
      int ret_val;

      g_mutex_lock (&mutex);
      ret_val = current_number = calc_next_number (current_number);
      g_mutex_unlock (&mutex);

      return ret_val;
    }

Notice that the GMutex is not initialised to any particular value. Its placement in static storage ensures that it will be initialised to all-zeros, which is appropriate.

If a GMutex is placed in other contexts (eg: embedded in a struct) then it must be explicitly initialised using `g_mutex_init()`.

A GMutex should only be accessed via g_mutex_ functions.

### GMutexLocker

    typedef void GMutexLocker;

Opaque type. See `g_mutex_locker_new()` for details.

Since: 2.44

### struct GRecMutex

    struct GRecMutex {
    };

The GRecMutex struct is an opaque data structure to represent a recursive mutex. It is similar to a GMutex with the difference that it is possible to lock a GRecMutex multiple times in the same thread without deadlock. When doing so, care has to be taken to unlock the recursive mutex as often as it has been locked.

If a GRecMutex is allocated in static storage then it can be used without initialisation. Otherwise, you should call `g_rec_mutex_init()` on it and `g_rec_mutex_clear()` when done.

A GRecMutex should only be accessed with the g_rec_mutex_ functions.

Since: 2.32

### struct GRWLock

    struct GRWLock {
    };

The GRWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a GMutex in that it allows multiple threads to coordinate access to a shared resource.

The difference to a mutex is that a reader-writer lock discriminates between read-only ('reader') and full ('writer') access. While only one thread at a time is allowed write access (by holding the 'writer' lock via `g_rw_lock_writer_lock()`), multiple threads can gain simultaneous read-only access (by holding the 'reader' lock via `g_rw_lock_reader_lock()`).

Here is an example for an array with access functions:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    GRWLock lock;
    GPtrArray *array;

    gpointer
    my_array_get (guint index)
    {
      gpointer retval = NULL;

      if (!array)
        return NULL;

      g_rw_lock_reader_lock (&lock);
      if (index < array->len)
        retval = g_ptr_array_index (array, index);
      g_rw_lock_reader_unlock (&lock);

      return retval;
    }

    void
    my_array_set (guint index, gpointer data)
    {
      g_rw_lock_writer_lock (&lock);

      if (!array)
        array = g_ptr_array_new ();

      if (index >= array->len)
        g_ptr_array_set_size (array, index+1);
      g_ptr_array_index (array, index) = data;

      g_rw_lock_writer_unlock (&lock);
    }

This example shows an array which can be accessed by many readers (the `my_array_get()` function) simultaneously, whereas the writers (the `my_array_set()` function) will only be allowed one at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now.

If a GRWLock is allocated in static storage then it can be used without initialisation. Otherwise, you should call `g_rw_lock_init()` on it and `g_rw_lock_clear()` when done.

A GRWLock should only be accessed with the g_rw_lock_ functions.

Since: 2.32

### struct GCond

    struct GCond {
    };

The GCond struct is an opaque data structure that represents a condition. Threads can block on a GCond if they find a certain condition to be false. If other threads change the state of this condition they signal the GCond, and that causes the waiting threads to be woken up.

Consider the following example of a shared variable. One or more threads can wait for data to be published to the variable and when another thread publishes the data, it can signal one of the waiting threads to wake up to collect the data.

Here is an example for using GCond to block a thread until a condition is satisfied:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    gpointer current_data = NULL;
    GMutex data_mutex;
    GCond data_cond;

    void
    push_data (gpointer data)
    {
      g_mutex_lock (&data_mutex);
      current_data = data;
      g_cond_signal (&data_cond);
      g_mutex_unlock (&data_mutex);
    }

    gpointer
    pop_data (void)
    {
      gpointer data;

      g_mutex_lock (&data_mutex);
      while (!current_data)
        g_cond_wait (&data_cond, &data_mutex);
      data = current_data;
      current_data = NULL;
      g_mutex_unlock (&data_mutex);

      return data;
    }

Whenever a thread calls `pop_data()` now, it will wait until current_data is non-`NULL`, i.e. until some other thread has called `push_data()`.

The example shows that use of a condition variable must always be paired with a mutex. Without the use of a mutex, there would be a race between the check of `current_data` by the while loop in `pop_data()` and waiting. Specifically, another thread could set `current_data` after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep. GCond is specifically useful for its ability to release the mutex and go to sleep atomically.

It is also important to use the `g_cond_wait()` and `g_cond_wait_until()` functions only inside a loop which checks for the condition to be true. See `g_cond_wait()` for an explanation of why the condition may not be true even after it returns.

If a GCond is allocated in static storage then it can be used without initialisation. Otherwise, you should call `g_cond_init()` on it and `g_cond_clear()` when done.

A GCond should only be accessed via the g_cond_ functions.

### struct GPrivate

    struct GPrivate {
    };

The GPrivate struct is an opaque data structure to represent a thread-local data key. It is approximately equivalent to the `pthread_setspecific()`/`pthread_getspecific()` APIs on POSIX and to `TlsSetValue()`/`TlsGetValue()` on Windows.

If you don't already know why you might want this functionality, then you probably don't need it.

GPrivate is a very limited resource (as far as 128 per program, shared between all libraries). It is also not possible to destroy a GPrivate after it has been used. As such, it is only ever acceptable to use GPrivate in static scope, and even then sparingly so.

See `G_PRIVATE_INIT()` for a couple of examples.

The GPrivate structure should be considered opaque. It should only be accessed via the g_private_ functions.

### struct GOnce

    struct GOnce {
      volatile GOnceStatus status;
      volatile gpointer retval;
    };

A GOnce struct controls a one-time initialization function. Any one-time initialization function must have its own unique GOnce struct.

#### Members

volatile GOnceStatus `status`; | the status of the GOnce |
volatile gpointer `retval`; | the value returned by the call to the function, if `status` is `G_ONCE_STATUS_READY` |

Since: 2.4

### enum GOnceStatus

The possible statuses of a one-time initialization function controlled by a GOnce struct.

#### Members

G_ONCE_STATUS_NOTCALLED | the function has not been called yet. |
G_ONCE_STATUS_PROGRESS | the function call is currently in progress. |
G_ONCE_STATUS_READY | the function has been called. |

Since: 2.4

### G_ONCE_INIT

    #define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }

A GOnce must be initialized with this macro before it can be used.

    1
    GOnce my_once = G_ONCE_INIT;

Since: 2.4

## See Also

GThreadPool, GAsyncQueue