GLib.Cond
Description: Reference for GLib.Cond

### Struct

# GLibCond

#### Description [src]

    struct GCond {
      /* No available fields */
    }

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:

      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.

#### Functions

###### g_cond_new

Allocates and initializes a new `GCond`.

deprecated: 2.32

#### Instance methods

###### g_cond_broadcast

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_cond_clear

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

since: 2.32

###### g_cond_free

Destroys a `GCond` that has been created with g_cond_new().

deprecated: 2.32

###### g_cond_init

Initialises a `GCond` so that it can be used.

since: 2.32

###### g_cond_signal

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_timed_wait

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.

deprecated: 2.32

###### g_cond_wait

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

###### g_cond_wait_until

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

since: 2.32