cond_wait(SYNCH)

cond_wait -- wait on a condition variable

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int cond_wait(cond_t *cond, mutex_t *mutex);

Description

cond_wait blocks the calling thread at the condition variable pointed to by cond to wait for the occurrence of a condition. The calling thread must lock the mutual exclusion lock (mutex) pointed to by mutex before calling cond_wait, otherwise the behavior is unpredictable.

cond_wait automatically releases the mutex, and waits on the condition variable cond. When the condition is signaled cond_wait reacquires the mutex and returns to the caller. The wait can also be interrupted by a UNIX system signal, in which case mutex is reacquired, the signal handler is called, and cond_wait returns EINTR.

The calling thread can resume execution when the condition is signaled or broadcast, or when interrupted. The logical condition should be checked on return, as a return might not have been caused by a change in the condition.

Parameters

cond: pointer to the condition variable to wait for
mutex: pointer to a locked mutex

cond parameter

The condition variable denoted by cond must previously have been initialized (see cond_init(SYNCH)).

mutex parameter

mutex is a mutual exclusion variable protecting a shared resource associated with the condition represented by the condition variable, cond. The calling thread must lock mutex before calling cond_wait, otherwise the behavior is unpredictable.

Usage

See the description of how to use condition variables under USAGE on condition(SYNCH).

Because the condition can change between the time the condition is signaled, and the mutex is relocked, the calling thread must always recheck the condition upon return from cond_wait.

Return values

cond_wait returns zero for success and an error number for failure.

Errors

If any of the following conditions is detected, cond_wait fails and returns the corresponding value:

EINTR: the wait was interrupted by a UNIX system signal
EINVAL: invalid argument specified

References

condition(SYNCH), cond_broadcast(SYNCH), cond_destroy(SYNCH), cond_init(SYNCH), cond_signal(SYNCH), cond_timedwait(SYNCH), mutex(SYNCH)