PTHREAD_COND_WAIT(3)

NAME
pthread_cond_wait, pthread_cond_timedwait - wait on a condition variable

LIBRARY
libpthread

SYNOPSIS
#include <pthread.h>
int
pthread_cond_wait(pthread_cond_t * restrict cond, pthread_mutex_t * restrict mutex);
int
pthread_cond_timedwait(pthread_cond_t * restrict cond, pthread_mutex_t * restrict mutex, const struct timespec * restrict abstime);

DESCRIPTION
The pthread_cond_wait() function atomically blocks the current thread waiting on the condition variable specified by cond, and unblocks the mutex specified by mutex. The waiting thread unblocks after another thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with the same condition variable. The current thread holds the lock on mutex upon return from the pthread_cond_wait call.

The pthread_cond_timedwait() function atomically blocks the current thread waiting on the condition variable specified by cond, and unblocks the mutex specified by mutex. The waiting thread unblocks after another thread calls pthread_cond_signal(3), or pthread_cond_broadcast(3) with the same condition variable, or if the system time reaches the time specified in abstime.

Note that a call to pthread_cond_wait() or pthread_cond_timedwait() may wake up spontaneously, without a call to pthread_cond_signal(3) or pthread_cond_broadcast(3). The caller should prepare for this by invoking pthread_cond_wait() or pthread_cond_timedwait() within a predicate loop that tests whether the thread should proceed.

When calling pthread_cond_wait() or pthread_cond_timedwait(), a temporary binding is established between the condition variable cond and the mutex mutex.

The same mutex must be held while calling pthread_cond_broadcast() and pthread_cond_signal() on cond. Additionally, the same mutex must be used for concurrent calls to pthread_cond_wait() and pthread_cond_timedwait(). Only when a condition variable is known to be quiescent may an application change the mutex associated with it. In this implementation, none of the functions enforce this requirement, but if the mutex is not held or independent mutexes are used the resulting behaviour is undefined.

RETURN VALUES
If successful, the pthread_cond_wait() and pthread_cond_timedwait() functions will return zero. Otherwise an error number will be returned to indicate the error.

ERRORS
pthread_cond_wait() may fail if:

[EINVAL]
    The value specified by cond or the value specified by mutex is invalid.

pthread_cond_timedwait() shall fail if:

[ETIMEDOUT]
    The system time has reached or exceeded the time specified in abstime.

pthread_cond_timedwait() may fail if:

[EINVAL]
    The value specified by cond, mutex, or abstime is invalid.

SEE ALSO
pthread_cond_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_signal(3)

STANDARDS
pthread_cond_wait() and pthread_cond_timedwait() conform to p1003.1-96.