condvar(9F)

NAME

condvar, cv_init, cv_destroy, cv_wait, cv_signal, cv_broadcast, cv_wait_sig, cv_timedwait − condition variable routines

SYNOPSIS

#include <sys/ksynch.h>

void cv_init(kcondvar_t ∗cvp, char ∗name, kcv_type_t type, void ∗arg);

void cv_destroy(kcondvar_t ∗cvp);

void cv_wait(kcondvar_t ∗cvp, kmutex_t ∗mp);

void cv_signal(kcondvar_t ∗cvp);

void cv_broadcast(kcondvar_t ∗cvp);

int cv_wait_sig(kcondvar_t ∗cvp, kmutex_t ∗mp);

int cv_timedwait(kcondvar_t ∗cvp, kmutex_t ∗mp, long timeout);

INTERFACE LEVEL

SPARC architecture specific (SPARC DDI).

ARGUMENTS

cvp A pointer to an abstract data type kcondvar_t.

mp A pointer to a mutual exclusion lock (kmutex_t), initialized by mutex_init(9F) and held by the caller.

name A name for the condition variable, used in statistics and debugging.

type The constant CV_DRIVER.

arg A type-specific argument, drivers should pass arg as NULL.

timeout A time, in absolute ticks since boot, when cv_timed_wait() should return.

DESCRIPTION

Condition variables are a standard form of thread synchronization. They are designed to be used with mutual exclusion locks (mutexes). The associated mutex is used to ensure that a condition can be checked atomically and that the thread can block on the associated condition variable without missing either a change to the condition or a signal that the condition has changed. Condition variables must be initialized by calling cv_init(), and must be deallocated by calling cv_destroy().

The usual use of condition variables is to check a condition (for example, device state, data structure reference count, etc.) while holding a mutex which keeps other threads from changing the condition. If the condition is such that the thread should block, cv_wait() is called with a related condition variable and the mutex.

cv_wait() suspends the calling thread and exits the mutex atomically so that another thread which holds the mutex cannot signal on the condition variable until the blocking thread is blocked. Before returning, the mutex is reacquired.

cv_signal() signals the condition and wakes one blocked thread. All blocked threads can be unblocked by calling cv_broadcast().

The function cv_wait_sig() is similar to cv_wait() but returns zero if a signal (for example, by kill(2)) is sent to the thread. In any case, the mutex is reacquired before returning.

The function cv_timedwait() is similar to cv_wait(), except that it returns zero without the condition being signaled after the timeout time has been reached. The time is in absolute clock ticks since the last system reboot. The current time may be found by calling drv_getparm(9F) with the argument LBOLT.

RETURN VALUES

0 For cv_wait_sig(), indicates that the condition was not necessarily signaled and the function returned because a signal was pending.

0 For cv_timedwait(), indicates that the condition was not necessarily signaled and the function returned because the timeout time was reached.

CONTEXT

These functions can be called from user or interrupt context. However, in most cases, cv_wait() and cv_timedwait() should be called from user context only. cv_wait_sig() should be called from user context only, since kernel threads and interrupts cannot receive signals.

EXAMPLES

Here the condition being waited for is a flag value in a driver’s unit structure. The condition variable is also in the unit structure, and the flag word is protected by a mutex in the unit structure.

mutex_enter(&un->un_lock);
while (un->un_flag & UNIT_BUSY)
cv_wait(&un->un_cv, &un->un_lock);
un->un_flag |= UNIT_BUSY;
mutex_exit(&un->un_lock);

Museum

Related Articles