condition(3synch)

Synopsis

   cc [options] -Kthread file
   

   #include <synch.h>
   

   int cond_init(cond_t *cond, int type, void *arg);
   

   int cond_signal(cond_t *cond);
   

   int cond_broadcast(cond_t *cond);
   

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

   int cond_timedwait(cond_t *cond, mutex_t *mutex, timestruc_t *abstime);
   

   int cond_destroy(cond_t *cond);

Description

A condition variable is always associated with some shared variables protected by a mutex and a predicate (or condition) based on those shared variables. A thread acquires the mutex and evaluates the predicate. If the predicate is false, the thread calls cond_wait (with the mutex as an argument) to wait for notification that the condition has changed. cond_wait blocks the caller and releases the mutex.

While the first thread is blocked, another thread may acquire the mutex and change the shared variables so that the predicate is now true. That thread can either call cond_signal to notify one thread or call cond_broadcast to notify all waiting threads, then it releases the mutex.

When a waiting thread receives notification using cond_signal or cond_broadcast that a condition has changed, cond_wait will unblock the thread and re-acquire the mutex. When the thread returns from cond_wait, it will hold the mutex. It must reevaluate the predicate, which might have become false again.

Unlike other user synchronization mechanisms, which have variables that can be locked or unlocked, condition variables are stateless. In addition, condition variables allow a thread either to signal one waiting thread that the condition has changed or to broadcast a signal to all waiting threads that a condition has changed.

Parameters

cond

pointer to condition variable to be initialized, signaled, waited for, or destroyed

type

USYNC_THREAD or USYNC_PROCESS

arg

NULL (reserved for future use)

mutex

pointer to a locked mutex

abstime

absolute time to at which to time out

cond_init

cond_signal

cond_signal has no effect if there are no threads waiting on cond.

A cond_signal will be more reliable if the associated mutex used by waiters is held across the call.

cond_broadcast

cond_broadcast has no effect if there are no threads waiting on cond.

A cond_broadcast will be more reliable if the associated mutex used by waiters is held across the call.

cond_wait

cond_wait automatically releases the mutex, and waits on the condition variable cond. When the condition is signaled or the wait is interrupted, cond_wait reacquires the mutex and returns to the caller. If the wait is interrupted, mutex is reacquired before a signal handler or any other user code can be executed.

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.

cond_timedwait

cond_timedwait automatically releases the mutex, and waits on the condition variable cond. When the condition is signaled, the time expires, or the wait is interrupted, cond_timedwait reacquires the mutex and returns to the caller. If the wait is interrupted, mutex is reacquired before a signal handler or any other user code can be executed.

User-visible timers are not affected by a call to cond_timedwait.

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

cond_destroy

USYNC_THREAD and USYNC_PROCESS condition variables

References