NAME

pthread_cond_wait, pthread_cond_timedwait - wait on a condition variable

LIBRARY

POSIX Thread Library (libpthread, -lpthread)

SYNOPSIS



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 ISO/IEC 9945-1:1996 (``POSIX.1'') .