NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES
#include <pthread.h> #include <time.h> pthread_cond_t cond = PTHREAD_COND_INITIALIZER;int pthread_cond_init(pthread_cond_t * cond, const pthread_condattr_t * attr);
The pthread_cond_init function initializes the condition variable referenced by cond with attributes obtained from attr . If attr is NULL, the default condition variable attributes are used.
A condition variable that is statically allocated may be initialized with the initializer macro PTHREAD_COND_INITIALIZER. The effect is equivalent to dynamic initialization using pthread_cond_init with attr equal to NULL, except that no error checks are performed.
The pthread_cond_destroy function deletes the condition variable designated by cond , if there are no threads currently blocked on it. Otherwise, pthread_cond_destroy returns an error.
The pthread_cond_signal function awakens one or more threads blocked on the condition variable cond . If there are multiple threads blocked on cond , they will be awakened in the order they blocked. The pthread_cond_broadcast function awakens all threads blocked on the condition variable cond .
Neither pthread_cond_signal nor pthread_cond_broadcast has any effect on the condition variable if there are no threads currently blocked on it.
The pthread_cond_wait and pthread_cond_timedwait functions cause a wait on the condition variable cond . They must be called with the mutex referenced by mutex locked by the calling thread. These functions atomically release mutex and block the calling thread. It is impossible for any other thread to acquire the mutex and invoke pthread_cond_signal or pthread_cond_broadcast so that those operations take effect between the release of the mutex and the block of the thread calling pthread_cond_wait or pthread_cond_timedwait .
Upon successful return from pthread_cond_wait or pthread_cond_timedwait , the mutex will have been re-acquired by the calling thread.
The pthread_cond_timedwait function is the same as pthread_cond_wait except that an error is returned in the following cases:
if the absolute time specified by abstime expires (that is, system time as measured by the realtime clock equals or exceeds abstime ) before the condition variable cond is signaled or broadcast
if the time specified by abstime has already expired at the time of the call
A condition variable wait is subject to spurious wakeups. Within the user program, a boolean predicate is usually associated with a condition variable. The predicate involves shared variables and is tested with the mutex locked. If it is found to be false, the thread blocks using a condition wait. As the return from pthread_cond_wait or pthread_cond_timedwait does not confirm anything about the value of the predicate, it is crucial to re-evaluate the predicate and be prepared to wait again if it is still false.
In effect, pthread_cond_wait and pthread_cond_timedwait establish a dynamic binding between a condition variable and a particular mutex. The effect of using more than one mutex for concurrent condition waits on the same condition variable is undefined.
Upon successful completion, all functions listed above return zero. Otherwise an error code is returned. (NOTE: These calls do not set errno .)
Except for ETIMEDOUT, all the error checks indicated are performed at the beginning of processing for the function, and error returns are made before any change is made to the state of any condition variable or mutex argument.
The cond argument does not refer to a valid condition variable. The mutex argument does not refer to a valid mutex ( pthread_cond_wait and pthread_cond_timedwait only). The abstime argument refers to an unusable time value ( pthread_cond_timedwait only).
The condition variable cond cannot be deleted because one or more threads are currently blocked on it ( pthread_cond_destroy only).
The time specified by abstime has passed ( pthread_cond_timedwait only).
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES