pthread_cond_init, pthread_cond_destroy, pthread_cond_signal,
pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait - operations
on conditions
#include <pthread.h>
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t
*cond_attr);
int pthread_cond_signal(pthread_cond_t *cond);
int pthread_cond_broadcast(pthread_cond_t *cond);
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t
*mutex);
int pthread_cond_timedwait(pthread_cond_t *cond,
pthread_mutex_t *mutex, const struct timespec
*abstime);
int pthread_cond_destroy(pthread_cond_t *cond);
A condition (short for ``condition variable'') is a synchronization device that
allows threads to suspend execution and relinquish the processors 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.
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.
pthread_cond_broadcast restarts all the threads that are waiting on the
condition variable
cond. Nothing happens if no threads are waiting on
cond.
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.
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 within the amount of time
specified by
abstime, the mutex
mutex is re-acquired and
pthread_cond_timedwait returns the error
ETIMEDOUT. The
abstime parameter specifies an absolute time, with the same origin as
time(2) and
gettimeofday(2): an
abstime of 0 corresponds
to 00:00:00 GMT, January 1, 1970.
pthread_cond_destroy destroys a condition variable, freeing the resources
it might hold. No threads must be waiting on the condition variable on
entrance to
pthread_cond_destroy. In the LinuxThreads implementation,
no resources are associated with condition variables, thus
pthread_cond_destroy actually does nothing except checking that the
condition has no waiting threads.
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, then locks again the
mutex
argument to
pthread_cond_wait and
pthread_cond_timedwait, and
finally executes the cancellation. Consequently, cleanup handlers are assured
that
mutex is locked when they are called.
The condition functions are not async-signal safe, and should not be called from
a signal handler. In particular, calling
pthread_cond_signal or
pthread_cond_broadcast from a signal handler may deadlock the calling
thread.
All condition variable functions return 0 on success and a non-zero error code
on error.
pthread_cond_init,
pthread_cond_signal,
pthread_cond_broadcast, and
pthread_cond_wait never return an
error code.
The
pthread_cond_timedwait function returns the following error codes on
error:
- ETIMEDOUT
- the condition variable was not signaled until the timeout
specified by abstime
- EINTR
-
pthread_cond_timedwait was interrupted by a
signal
The
pthread_cond_destroy function returns the following error code on
error:
- EBUSY
- some threads are currently waiting on cond.
Xavier Leroy <
[email protected]>
pthread_condattr_init(3),
pthread_mutex_lock(3),
pthread_mutex_unlock(3),
gettimeofday(2),
nanosleep(2).
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);