Cond

class Cond(*args, **kwargs)

Constructors:

Cond()

Methods

class Cond

broadcast() → None

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() → None

Frees the resources allocated to a Cond with init().

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

Calling clear() for a Cond on which threads are blocking leads to undefined behaviour.

Added in version 2.32.

init() → None

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 init() when a Cond is no longer needed, use clear().

Calling init() on an already-initialised Cond leads to undefined behaviour.

Added in version 2.32.

signal() → None

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(mutex: Mutex) → None

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

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

Parameters:

mutex – a Mutex that is currently locked

wait_until(mutex: Mutex, end_time: int) → bool

Waits until either cond is signalled or end_time has passed.

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

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

Added in version 2.32.

Parameters:

• mutex – a Mutex that is currently locked

• end_time – the monotonic time to wait until

Fields

class Cond

i

p