GI.GLib.Structs.Cond

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

C code

 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-Nothing, 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 currentData by the while loop in pop_data() and waiting. Specifically, another thread could set currentData after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep. Cond is specifically useful for its ability to release the mutex and go to sleep atomically.

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

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

A Cond should only be accessed via the g_cond_ functions.

Exported types

newtype Cond

Memory-managed wrapper type.

Constructors

Cond (ManagedPtr Cond)

Instances

Eq Cond

Defined in GI.GLib.Structs.Cond

Methods

(==) :: Cond -> Cond -> Bool

(/=) :: Cond -> Cond -> Bool

ManagedPtrNewtype Cond

Defined in GI.GLib.Structs.Cond

Methods

toManagedPtr :: Cond -> ManagedPtr Cond

BoxedPtr Cond

Defined in GI.GLib.Structs.Cond

Methods

boxedPtrCopy :: Cond -> IO Cond

boxedPtrFree :: Cond -> IO ()

CallocPtr Cond

Defined in GI.GLib.Structs.Cond

Methods

boxedPtrCalloc :: IO (Ptr Cond)

tag ~ 'AttrSet => Constructible Cond tag

Defined in GI.GLib.Structs.Cond

Methods

new :: MonadIO m => (ManagedPtr Cond -> Cond) -> [AttrOp Cond tag] -> m Cond

newZeroCond :: MonadIO m => m Cond

Construct a Cond struct initialized to zero.

Methods

Overloaded methods

broadcast

condBroadcast

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: a Cond

-> m ()

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

condClear

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: an initialised Cond

-> m ()

Frees the resources allocated to a Cond with condInit.

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

Calling condClear for a Cond on which threads are blocking leads to undefined behaviour.

Since: 2.32

init

condInit

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: an uninitialized Cond

-> m ()

Initialises a Cond so that it can be used.

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

To undo the effect of condInit when a Cond is no longer needed, use condClear.

Calling condInit on an already-initialised Cond leads to undefined behaviour.

Since: 2.32

signal

condSignal

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: a Cond

-> m ()

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

condWait

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: a Cond

-> Mutex

mutex: a Mutex that is currently locked

-> m ()

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: condWait returns even though condSignal was not called). It's also possible that a stolen wakeup may occur. This is when condSignal is called, but another thread acquires mutex before this thread and modifies the state of the program in such a way that when condWait is able to return, the expected condition is no longer met.

For this reason, condWait must always be used in a loop. See the documentation for Cond for a complete example.

waitUntil

condWaitUntil

Arguments

:: (HasCallStack, MonadIO m)

=> Cond

cond: a Cond

-> Mutex

mutex: a Mutex that is currently locked

-> Int64

endTime: the monotonic time to wait until

-> m Bool

Returns: True on a signal, False on a timeout

Waits until either cond is signalled or endTime has passed.

As with condWait 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 endTime 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 Cond):

C code

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