pthread_cond_wait(3)pthread_cond_wait(3)NAMEpthread_cond_wait - Causes a thread to wait for the specified condition
variable to be signaled or broadcasted
SYNOPSIS
#include <pthread.h>
int pthread_cond_wait(
pthread_cond_t *cond,
pthread_mutex_t *mutex );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
Condition variable that the calling thread waits on. Mutex associated
with the condition variable specified in cond.
DESCRIPTION
This routine causes a thread to wait for the specified condition vari‐
able to be signaled or broadcasted. Each condition corresponds to one
or more Boolean relations, called a predicate, based on shared data.
The calling thread waits for the data to reach a particular state for
the predicate to become true. However, the return from this routine
does not imply anything about the value of the predicate, and it should
be reevaluated upon return.
Call this routine after you have locked the mutex specified in mutex.
The results of this routine are unpredictable if this routine is called
without first locking the mutex.
This routine atomically releases the mutex and causes the calling
thread to wait on the condition. When the thread regains control after
calling pthread_cond_wait(3), the mutex is locked and the thread is the
owner. This is true regardless of why the wait ended. If general cance‐
lability is enabled, the thread reacquires the mutex (blocking for it
if necessary) before the cleanup handlers are run (or before the excep‐
tion is raised).
A thread that changes the state of storage protected by the mutex in
such a way that a predicate associated with a condition variable might
now be true, must call either pthread_cond_signal(3) or
pthread_cond_broadcast(3) for that condition variable. If neither call
is made, any thread waiting on the condition variable continues to
wait.
This routine might (with low probability) return when the condition
variable has not been signaled or broadcasted. When this occurs, the
mutex is reacquired before the routine returns. To handle this type of
situation, enclose each call to this routine in a loop that checks the
predicate. The loop provides documentation of your intent and protects
against these spurious wakeups, while also allowing correct behavior
even if another thread consumes the desired state before the awakened
thread runs.
It is illegal for threads to wait on the same condition variable by
specifying different mutexes.
The only routines which are supported for use with asynchronous cance‐
lability enabled are those which disable asynchronous cancelability.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error. Possible return values are as follows:
Successful completion. The value specified by cond, or mutex is
invalid, or: Different mutexes are supplied for concurrent
pthread_cond_wait(3) operations or pthread_cond_timedwait operations on
the same condition variable, or: The mutex was not owned by the calling
thread at the time of the call. DECthreads cannot acquire memory
needed to block using a statically initialized condition variable.
ERRORS
None
SEE ALSO
Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3),
pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_timed‐
wait(3),
Manuals: Guide to DECthreads and Programmer's Guide
pthread_cond_wait(3)