NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES
$(OS_DIR)/lib/libpthreads.a #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 function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
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 in which they blocked. The pthread_cond_broadcast() function awakens all threads blocked on the condition variable cond .
The pthread_cond_signal() and pthread_cond_broadcast() functions have no 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() .
On successful return from pthread_cond_wait() or pthread_cond_timedwait() , the mutex will have been retrieved 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.
On successful completion, all functions listed above return zero. Otherwise an error code is returned.
These calls do not set errno .
Except for ETIMEDOUT, all the error checks indicated are performed at the beginning of processing for the function. Errors are returned before changes are 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 attr ibutes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES