pthread_cond_wait(3P)pthread_cond_wait(3P)NAME
pthread_cond_init, pthread_cond_signal, pthread_cond_broadcast,
pthread_cond_wait, pthread_cond_timedwait, pthread_cond_destroy -
condition variables
C SYNOPSIS
#include <pthread.h>
int pthread_cond_init(pthread_cond_t *cond,
const pthread_condattr_t *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
Condition variables provide high performance synchronization primitives
to wait for or wake up threads waiting for certain conditions to be
satisfied. Functions are provided to wait on a condition variable and to
wake up (signal) threads that are waiting on the condition variable.
Initialize
Condition variables may be initialized either dynamically, by calling
pthread_cond_init(), or statically, via the macro
PTHREAD_COND_INITIALIZER.
The personality of the condition variable is determined by the attribute
structure attr passed with the call to pthread_cond_init(). These
attributes are set by calls to pthread_condattr_init() and the various
condition variable attribute functions. If attr is null (or the
condition variable is statically initialized) the default attributes are
used.
Wait
The functions pthread_cond_wait() and pthread_cond_timedwait() are used
to block on a condition variable. They must be called with mutex locked
by the calling thread. The functions atomically release mutex and block
the calling thread on the condition variable cond. Before return, the
mutex is reacquired for the calling thread.
A condition wait is a cancellation point [see pthread_cancel()]. When
the cancelability enable state of a thread is set to
PTHREAD_CANCEL_DEFERRED, a side-effect of acting on a cancellation
request while in a condition wait is that the mutex is re-acquired before
Page 1
pthread_cond_wait(3P)pthread_cond_wait(3P)
calling the first cancellation handler. A thread that has been unblocked
because it has been cancelled while waiting on a condition variable does
not consume any condition signal that may be directed at the condition
variable.
The function pthread_cond_timedwait() is the same as pthread_cond_wait()
except that an error is returned if the absolute time (that is, system or
wall-clock time) specified by abstime passes before the waiting thread is
signalled. If a time-out occurs, pthread_cond_timedwait() still
reacquires mutex before returning to the caller.
Signal
The functions pthread_cond_signal() and pthread_cond_broadcast() are used
to unblock threads waiting on a condition variable.
The pthread_cond_signal() function unblocks one of the threads that are
blocked on cond; at the time of the call. The function
pthread_cond_broadcast() unblocks all threads blocked on the specified
condition variable at the time of the call.
If more than one thread is blocked on a condition variable, the
scheduling policy determines the order in which threads are unblocked.
Calls to pthread_cond_signal() and pthread_cond_broadcast() have no
effect if there are no threads blocked on the condition variable at the
time of the calls.
A thread may call pthread_cond_signal() or pthread_cond_broadcast()
without holding the mutex with which threads calling pthread_cond_wait()
or pthread_cond_timedwait() have associated with the condition variable
during their waits. However, predictable scheduling behavior is only
guaranteed if the associated mutex is locked by a thread calling
pthread_cond_signal() or pthread_cond_broadcast().
Destroy
The routine pthread_cond_destroy() de-initializes the condition variable
object referenced by cond; the condition variable object becomes
uninitialized.
DIAGNOSTICS
All of the condition variable functions return zero if successful;
otherwise, an error number is returned.
pthread_cond_destroy() can return the following error:
[EBUSY] The condition variable is currently being used by one or
more threads.
pthread_cond_timedwait() can return the following errors:
[ETIMEDOUT] The timeout occurred before the thread was awakened by
pthread_cond_signal() or pthread_cond_broadcast().
Page 2
pthread_cond_wait(3P)pthread_cond_wait(3P)
[EINVAL] No timespec structure was passed or the contents of the
timespec structure were invalid.
SEE ALSOpthread_cancel(3P), pthread_condattr_init(3P), pthread_mutex_lock(3P),
pthread_mutex_unlock(3P).
NOTES
A return from pthread_cond_wait() or pthread_cond_timedwait() does not
guarantee that the condition or event for which the caller was waiting
actually occurred. It is the responsibility of the call to recheck the
condition wait predicate before proceeding.
Page 3
