Cond

The glib.Cond struct is an opaque data structure that represents a condition. Threads can block on a glib.Cond if they find a certain condition to be false. If other threads change the state of this condition they signal the glib.Cond, 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;
}

henever 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. glib.Cond is specifically useful for its ability to release the mutex and go to sleep atomically.

It is also important to use the Cond.wait and Cond.waitUntil functions only inside a loop which checks for the condition to be true. See Cond.wait for an explanation of why the condition may not be true even after it returns.

If a glib.Cond is allocated in static storage then it can be used without initialisation. Otherwise, you should call Cond.init on it and Cond.clear when done.

A glib.Cond should only be accessed via the g_cond_ functions.

class Cond {

protected

GCond* gCond;

protected

bool ownedRef;

GCond* getCondStruct(bool transferOwnership);

void* getStruct();

this(GCond* gCond, bool ownedRef);

void wait(Mutex mutex);

bool waitUntil(Mutex mutex, long endTime);

}

Constructors

this this(GCond* gCond, bool ownedRef): Sets our main struct and passes it to the parent class.

Members

Functions

broadcast void 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.
clear void clear(): Frees the resources allocated to a glib.Cond with Cond.init.
getCondStruct GCond* getCondStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
init void init(): Initialises a glib.Cond so that it can be used.
signal void 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.
wait void wait(Mutex mutex): Atomically releases mutex and waits until cond is signalled. When this function returns, mutex is locked again and owned by the calling thread.
waitUntil bool waitUntil(Mutex mutex, long endTime): Waits until either cond is signalled or end_time has passed.

Variables

gCond GCond* gCond;: the main Gtk struct

glib Cond classes

Cond