A condition (short for "condition variable") is a synchronization device that allows threads to suspend execution until some predicate on shared data is satisfied. The basic operations on conditions are: signal the condition (when the predicate becomes true), and wait for the condition, suspending the thread execution until another thread signals the condition.
A condition variable must always be associated with a mutex, to avoid the race condition where a thread prepares to wait on a condition variable and another thread signals the condition just before the first thread actually waits on it.
pthread_cond_init
initializes the condition variable cond,
using the condition attributes specified in cond_attr, or default
attributes if cond_attr is NULL
. The LinuxThreads
implementation supports no attributes for conditions, hence the
cond_attr parameter is actually ignored.
Variables of type pthread_cond_t
can also be initialized
statically, using the constant PTHREAD_COND_INITIALIZER
.
This function always returns 0.
pthread_cond_signal
restarts one of the threads that are waiting
on the condition variable cond. If no threads are waiting on
cond, nothing happens. If several threads are waiting on
cond, exactly one is restarted, but it is not specified which.
This function always returns 0.
pthread_cond_broadcast
restarts all the threads that are waiting
on the condition variable cond. Nothing happens if no threads are
waiting on cond.
This function always returns 0.
pthread_cond_wait
atomically unlocks the mutex (as per
pthread_unlock_mutex
) and waits for the condition variable
cond to be signaled. The thread execution is suspended and does
not consume any CPU time until the condition variable is signaled. The
mutex must be locked by the calling thread on entrance to
pthread_cond_wait
. Before returning to the calling thread,
pthread_cond_wait
re-acquires mutex (as per
pthread_lock_mutex
).
Unlocking the mutex and suspending on the condition variable is done atomically. Thus, if all threads always acquire the mutex before signaling the condition, this guarantees that the condition cannot be signaled (and thus ignored) between the time a thread locks the mutex and the time it waits on the condition variable.
This function always returns 0.
pthread_cond_timedwait
atomically unlocks mutex and waits
on cond, as pthread_cond_wait
does, but it also bounds the
duration of the wait. If cond has not been signaled before time
abstime, the mutex mutex is re-acquired and
pthread_cond_timedwait
returns the error code ETIMEDOUT
.
The wait can also be interrupted by a signal; in that case
pthread_cond_timedwait
returns EINTR
.
The abstime parameter specifies an absolute time, with the same
origin as time
and gettimeofday
: an abstime of 0
corresponds to 00:00:00 GMT, January 1, 1970.
pthread_cond_destroy
destroys the condition variable cond,
freeing the resources it might hold. If any threads are waiting on the
condition variable, pthread_cond_destroy
leaves cond
untouched and returns EBUSY
. Otherwise it returns 0, and
cond must not be used again until it is reinitialized.
In the LinuxThreads implementation, no resources are associated with
condition variables, so pthread_cond_destroy
actually does
nothing.
pthread_cond_wait
and pthread_cond_timedwait
are
cancellation points. If a thread is cancelled while suspended in one of
these functions, the thread immediately resumes execution, relocks the
mutex specified by mutex, and finally executes the cancellation.
Consequently, cleanup handlers are assured that mutex is locked
when they are called.
It is not safe to call the condition variable functions from a signal
handler. In particular, calling pthread_cond_signal
or
pthread_cond_broadcast
from a signal handler may deadlock the
calling thread.
Consider two shared variables x and y, protected by the mutex mut, and a condition variable cond that is to be signaled whenever x becomes greater than y.
int x,y; pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
Waiting until x is greater than y is performed as follows:
pthread_mutex_lock(&mut); while (x <= y) { pthread_cond_wait(&cond, &mut); } /* operate on x and y */ pthread_mutex_unlock(&mut);
Modifications on x and y that may cause x to become greater than y should signal the condition if needed:
pthread_mutex_lock(&mut); /* modify x and y */ if (x > y) pthread_cond_broadcast(&cond); pthread_mutex_unlock(&mut);
If it can be proved that at most one waiting thread needs to be waken
up (for instance, if there are only two threads communicating through
x and y), pthread_cond_signal
can be used as a slightly more
efficient alternative to pthread_cond_broadcast
. In doubt, use
pthread_cond_broadcast
.
To wait for x to becomes greater than y with a timeout of 5 seconds, do:
struct timeval now; struct timespec timeout; int retcode; pthread_mutex_lock(&mut); gettimeofday(&now); timeout.tv_sec = now.tv_sec + 5; timeout.tv_nsec = now.tv_usec * 1000; retcode = 0; while (x <= y && retcode != ETIMEDOUT) { retcode = pthread_cond_timedwait(&cond, &mut, &timeout); } if (retcode == ETIMEDOUT) { /* timeout occurred */ } else { /* operate on x and y */ } pthread_mutex_unlock(&mut);
Condition attributes can be specified at condition creation time, by
passing a condition attribute object as second argument to
pthread_cond_init
. Passing NULL
is equivalent to passing
a condition attribute object with all attributes set to their default
values.
The LinuxThreads implementation supports no attributes for conditions. The functions on condition attributes are included only for compliance with the POSIX standard.
pthread_condattr_init
initializes the condition attribute object
attr and fills it with default values for the attributes.
pthread_condattr_destroy
destroys the condition attribute object
attr.
Both functions do nothing in the LinuxThreads implementation.
pthread_condattr_init
and pthread_condattr_destroy
always
return 0.
Go to the first, previous, next, last section, table of contents.