PTHREAD_COND(3)
NAME
pthread_cond_init, pthread_cond_destroy, pthread_cond_sig-
nal, pthread_cond_broadcast, pthread_cond_wait,
pthread_cond_timedwait - operations on conditions
SYNOPSIS
#include <<pthread.h>>
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
int pthread_cond_init(pthread_cond_t *cond, pthread_con-
dattr_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);
DESCRIPTION
A condition (short for ``condition variable'') is a syn-
chronization device that allows threads to suspend execu-
tion and relinquish the processors until some predicate on
shared data is satisfied. The basic operations on condi-
tions are: signal the condition (when the predicate
becomes true), and wait for the condition, suspending the
thread execution until another thread signals the condi-
tion.
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 vari-
able 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 abso-
lute time, with the same origin as time(2) and gettimeof-
day(2): an abstime of 0 corresponds to 00:00:00 GMT, Jan-
uary 1, 1970.
pthread_cond_destroy destroys a condition variable, free-
ing the resources it might hold. No threads must be wait-
ing 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.
CANCELLATION
pthread_cond_wait and pthread_cond_timedwait are cancella-
tion 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.
ASYNC-SIGNAL SAFETY
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.
RETURN VALUE
All condition variable functions return 0 on success and a
non-zero error code on error.
ERRORS
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.
AUTHOR
Xavier Leroy lt;Xavier.Leroy@inria.fr
SEE ALSO
pthread_condattr_init(3) pthread_mutex_lock(3)
pthread_mutex_unlock(3) gettimeofday(2) nanosleep(2).
EXAMPLE
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_mutex_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_sig-
nal 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);