GThreadFunc ()

gpointer
(*GThreadFunc) (gpointer user_data);

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

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.

New threads by default inherit their scheduler policy (POSIX) or thread priority (Windows) of the thread creating the new thread.

This behaviour changed in GLib 2.64: before threads on Windows were not inheriting the thread priority but were spawned with the default priority. Starting with GLib 2.64 the behaviour is now consistent between Windows and POSIX and all threads inherit their parent thread's priority.

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.

Since: 2.32

g_thread_ref ()

GThread *
g_thread_ref (GThread *thread);

Increase the reference count on 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.

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.

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.

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.

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.

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.

Since: 2.32

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).

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).

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.

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.

No allocation is performed, it is equivalent to a g_mutex_lock() call.

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
}

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.

No memory is freed, it is equivalent to a g_mutex_unlock() call.

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;
}

G_LOCK_DEFINE_STATIC()

#define G_LOCK_DEFINE_STATIC(name)

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

G_LOCK_EXTERN()

#define G_LOCK_EXTERN(name)    

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

G_LOCK()

#define G_LOCK(name)

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

G_TRYLOCK()

#define G_TRYLOCK(name)

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

G_UNLOCK()

#define G_UNLOCK(name)

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

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().

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.

Since: 2.32

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.

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.

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.

Since: 2.32

g_rec_mutex_locker_new ()

GRecMutexLocker *
g_rec_mutex_locker_new (GRecMutex *rec_mutex);

Lock rec_mutex and return a new GRecMutexLocker. Unlock with g_rec_mutex_locker_free(). Using g_rec_mutex_unlock() on rec_mutex while a GRecMutexLocker exists can lead to undefined behaviour.

No allocation is performed, it is equivalent to a g_rec_mutex_lock() call.

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
{
  ...
  GRecMutex rec_mutex;
  ...
} MyObject;

static void
my_object_do_stuff (MyObject *self)
{
  g_autoptr(GRecMutexLocker) locker = g_rec_mutex_locker_new (&self->rec_mutex);

  // Code with rec_mutex locked here

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

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

  // Code with rec_mutex unlocked here
}

Since: 2.60

g_rec_mutex_locker_free ()

void
g_rec_mutex_locker_free (GRecMutexLocker *locker);

Unlock locker 's recursive mutex. See g_rec_mutex_locker_new() for details.

No memory is freed, it is equivalent to a g_rec_mutex_unlock() call.

Since: 2.60

g_rw_lock_writer_locker_new ()

GRWLockWriterLocker *
g_rw_lock_writer_locker_new (GRWLock *rw_lock);

Obtain a write lock on rw_lock and return a new GRWLockWriterLocker. Unlock with g_rw_lock_writer_locker_free(). Using g_rw_lock_writer_unlock() on rw_lock while a GRWLockWriterLocker exists can lead to undefined behaviour.

No allocation is performed, it is equivalent to a g_rw_lock_writer_lock() call.

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
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

typedef struct
{
  ...
  GRWLock rw_lock;
  GPtrArray *array;
  ...
} MyObject;

static gchar *
my_object_get_data (MyObject *self, guint index)
{
  g_autoptr(GRWLockReaderLocker) locker = g_rw_lock_reader_locker_new (&self->rw_lock);

  // Code with a read lock obtained on rw_lock here

  if (self->array == NULL)
    // No need to unlock
    return NULL;

  if (index < self->array->len)
    // No need to unlock
    return g_ptr_array_index (self->array, index);

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

  // Code with rw_lock unlocked here
  return NULL;
}

static void
my_object_set_data (MyObject *self, guint index, gpointer data)
{
  g_autoptr(GRWLockWriterLocker) locker = g_rw_lock_writer_locker_new (&self->rw_lock);

  // Code with a write lock obtained on rw_lock here

  if (self->array == NULL)
    self->array = g_ptr_array_new ();

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

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

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

  // Code with rw_lock unlocked here
}

Since: 2.62

g_rw_lock_writer_locker_free ()

void
g_rw_lock_writer_locker_free (GRWLockWriterLocker *locker);

Release a write lock on locker 's read-write lock. See g_rw_lock_writer_locker_new() for details.

No memory is freed, it is equivalent to a g_rw_lock_writer_unlock() call.

Since: 2.62

g_rw_lock_reader_locker_new ()

GRWLockReaderLocker *
g_rw_lock_reader_locker_new (GRWLock *rw_lock);

Obtain a read lock on rw_lock and return a new GRWLockReaderLocker. Unlock with g_rw_lock_reader_locker_free(). Using g_rw_lock_reader_unlock() on rw_lock while a GRWLockReaderLocker exists can lead to undefined behaviour.

No allocation is performed, it is equivalent to a g_rw_lock_reader_lock() call.

This is intended to be used with g_autoptr(). For a code sample, see g_rw_lock_writer_locker_new().

Since: 2.62

g_rw_lock_reader_locker_free ()

void
g_rw_lock_reader_locker_free (GRWLockReaderLocker *locker);

Release a read lock on locker 's read-write lock. See g_rw_lock_reader_locker_new() for details.

No memory is freed, it is equivalent to a g_rw_lock_reader_unlock() call.

Since: 2.62

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.

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.

Since: 2.32

g_rw_lock_writer_lock ()

void
g_rw_lock_writer_lock (GRWLock *rw_lock);

Obtain a write lock on rw_lock . If another thread currently 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 .

Calling g_rw_lock_writer_lock() while the current thread already owns a read or write lock on rw_lock leads to undefined behaviour.

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 another thread currently holds a read or write lock on rw_lock , it immediately returns FALSE. Otherwise it locks rw_lock and returns TRUE.

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.

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 , the current thread will block until the write lock was (held and) released. If another thread does not hold the write lock, but is waiting for it, it is implementation defined whether the reader or writer will block. Read locks can be taken recursively.

Calling g_rw_lock_reader_lock() while the current thread already owns a write lock leads to undefined behaviour. Read locks however can be taken recursively, in which case you need to make sure to call g_rw_lock_reader_unlock() the same amount of times.

It is implementation-defined how many read locks are allowed to be held on the same lock simultaneously. If the limit is hit, or if a deadlock is detected, a critical warning will be emitted.

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.

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.

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.

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.

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.

g_cond_timed_wait ()

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

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_real_time() and g_time_val_add() can be used.

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).

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.

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.

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 with 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));
}

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).

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.

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.

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;
}

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

While location has a volatile qualifier, this is a historical artifact and the pointer passed to it should not be volatile.

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.

While location has a volatile qualifier, this is a historical artifact and the pointer passed to it should not be volatile.

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. While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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. While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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. While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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.

While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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.

While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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.

While address has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

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.

Since: 2.36

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.

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

GRecMutexLocker

typedef void GRecMutexLocker;

Opaque type. See g_rec_mutex_locker_new() for details.

Since: 2.60

GRWLockWriterLocker

typedef void GRWLockWriterLocker;

Opaque type. See g_rw_lock_writer_locker_new() for details.

Since: 2.62

GRWLockReaderLocker

typedef void GRWLockReaderLocker;

Opaque type. See g_rw_lock_reader_locker_new() for details.

Since: 2.62

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()).

It is unspecified whether readers or writers have priority in acquiring the lock when a reader already holds the lock and a writer is queued to acquire it.

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.

Since: 2.4

enum GOnceStatus

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

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