CONDVAR(9)

CONDVAR(9) | Kernel Developer's Manual | CONDVAR(9)

# NAME

`cv`, `condvar`, `cv_init`, `cv_destroy`, `cv_wait`, `cv_wait_sig`, `cv_timedwait`, `cv_timedwait_sig`, `cv_timedwaitbt`, `cv_timedwaitbt_sig`, `cv_signal`, `cv_broadcast`, `cv_has_waiters` — condition variables

# SYNOPSIS

`#include <sys/condvar.h>`

void
`cv_init`(kcondvar_t *cv, const char *wmesg);

void
`cv_destroy`(kcondvar_t *cv);

void
`cv_wait`(kcondvar_t *cv, kmutex_t *mtx);

int
`cv_wait_sig`(kcondvar_t *cv, kmutex_t *mtx);

int
`cv_timedwait`(kcondvar_t *cv, kmutex_t *mtx, int ticks);

int
`cv_timedwait_sig`(kcondvar_t *cv, kmutex_t *mtx, int ticks);

int
`cv_timedwaitbt`(kcondvar_t *cv, kmutex_t *mtx, struct bintime *bt, const struct bintime *epsilon);

int
`cv_timedwaitbt_sig`(kcondvar_t *cv, kmutex_t *mtx, struct bintime *bt, const struct bintime *epsilon);

void
`cv_signal`(kcondvar_t *cv);

void
`cv_broadcast`(kcondvar_t *cv);

bool
`cv_has_waiters`(kcondvar_t *cv);

`options DIAGNOSTIC`
`options LOCKDEBUG`

# DESCRIPTION

Condition variables (CVs) are used in the kernel to synchronize access to resources that are limited (for example, memory) and to wait for pending I/O operations to complete.

The kcondvar_t type provides storage for the CV object. This should be treated as an opaque object and not examined directly by consumers.

# OPTIONS

`options DIAGNOSTIC`

  Kernels compiled with the `DIAGNOSTIC` option perform basic sanity checks on CV operations.

`options LOCKDEBUG`

  Kernels compiled with the `LOCKDEBUG` option perform potentially CPU intensive sanity checks on CV operations.

# FUNCTIONS

`cv_init`(cv, wmesg)

  Initialize a CV for use. No other operations can be performed on the CV until it has been initialized.

  The wmesg argument specifies a string of no more than 8 characters that describes the resource or condition associated with the CV. The kernel does not use this argument directly but makes it available for utilities such as ps(1) to display.

`cv_destroy`(cv)

  Release resources used by a CV. If there could be waiters, they should be awoken first with `cv_broadcast`(). The CV must not be used afterwards.

`cv_wait`(cv, mtx)

  Cause the current LWP to wait non-interruptably for access to a resource, or for an I/O operation to complete. The LWP will resume execution when awoken by another thread using `cv_signal`() or `cv_broadcast`().

  mtx specifies a kernel mutex to be used as an interlock, and must be held by the calling LWP on entry to `cv_wait`(). It will be released once the LWP has prepared to sleep, and will be reacquired before `cv_wait`() returns.

  A small window exists between testing for availability of a resource and waiting for the resource with `cv_wait`(), in which the resource may become available again. The interlock is used to guarantee that the resource will not be signalled as available until the calling LWP has begun to wait for it.

  Non-interruptable waits have the potential to deadlock the system, and so must be kept short (typically, under one second).

  `cv_wait`() is typically used within a loop or restartable code sequence, because it may awaken spuriously. The calling LWP should re-check the condition that caused the wait. If necessary, the calling LWP may call `cv_wait`() again to continue waiting.

`cv_wait_sig`(cv, mtx)

  As per `cv_wait`(), but causes the current LWP to wait interruptably. If the LWP receives a signal, or is interrupted by another condition such as its containing process exiting, the wait is ended early and an error code returned.

  If `cv_wait_sig`() returns as a result of a signal, the return value is `ERESTART` if the signal has the `SA_RESTART` property. If awoken normally, the value is zero, and `EINTR` under all other conditions.

`cv_timedwait`(cv, mtx, ticks)

  As per `cv_wait`(), but will return early if a timeout specified by the ticks argument expires.

  ticks is an architecture and system dependent value related to the number of clock interrupts per second. See hz(9) for details. The mstohz(9) macro can be used to convert a timeout expressed in milliseconds to one suitable for `cv_timedwait`(). If the ticks argument is zero, `cv_timedwait`() behaves exactly like `cv_wait`().

  If the timeout expires before the LWP is awoken, the return value is `EWOULDBLOCK`. If awoken normally, the return value is zero.

`cv_timedwait_sig`(cv, mtx, ticks)

  As per `cv_wait_sig`(), but also accepts a timeout value and will return `EWOULDBLOCK` if the timeout expires.

`cv_timedwaitbt`(cv, mtx, bt, epsilon)
`cv_timedwaitbt_sig`(cv, mtx, bt, epsilon)

  As per `cv_wait`() and `cv_wait_sig`(), but will return early if the duration bt has elapsed, immediately if bt is zero. On return, `cv_timedwaitbt`() and `cv_timedwaitbt_sig`() subtract the time elapsed from bt in place, or set it to zero if there is no time remaining.

  Note that `cv_timedwaitbt`() and `cv_timedwaitbt_sig`() may return zero indicating success, rather than `EWOULDBLOCK`, even if they set the timeout to zero; this means that the caller must re-check the condition in order to avoid potentially losing a `cv_signal`(), but the next wait will time out immediately.

  The hint epsilon, which can be `DEFAULT_TIMEOUT_EPSILON` if in doubt, requests that the wakeup not be delayed more than bt `+` epsilon, so that the system can coalesce multiple wakeups within their respective epsilons into a single high-resolution clock interrupt or choose to use cheaper low-resolution clock interrupts instead.

  However, the system is still limited by its best clock interrupt resolution and by scheduling competition, which may delay the wakeup by more than bt `+` epsilon.

`cv_signal`(cv)

  Awaken one LWP waiting on the specified condition variable. Where there are waiters sleeping non-interruptaby, more than one LWP may be awoken. This can be used to avoid a "thundering herd" problem, where a large number of LWPs are awoken following an event, but only one LWP can process the event.

  The mutex passed to the wait function (mtx) should be held or have been released immediately before `cv_signal`() is called.

  (Note that `cv_signal`() is erroneously named in that it does not send a signal in the traditional sense to LWPs waiting on a CV.)

`cv_broadcast`(cv)

  Awaken all LWPs waiting on the specified condition variable.

  As with `cv_signal`(), the mutex passed to the wait function (mtx) should be held or have been released immediately before `cv_broadcast`() is called.

`cv_has_waiters`(cv)

  Return `true` if one or more LWPs are waiting on the specified condition variable.

  `cv_has_waiters`() cannot test reliably for interruptable waits. It should only be used to test for non-interruptable waits made using `cv_wait`().

  `cv_has_waiters`() should only be used when making diagnostic assertions, and must be called while holding the interlocking mutex passed to `cv_wait`().

# EXAMPLES

Consuming a resource:

    	/*
    	 * Lock the resource.  Its mutex will also serve as the
    	 * interlock.
    	 */
    	mutex_enter(&res->mutex);

    	/*
    	 * Wait for the resource to become available.  Timeout after
    	 * five seconds.  If the resource is not available within the
    	 * allotted time, return an error.
    	 */
    	struct bintime timeout = { .sec = 5, .frac = 0 };
    	while (res->state == BUSY) {
    		error = cv_timedwaitbt(&res->condvar,
    		    &res->mutex, &timeout, DEFAULT_TIMEOUT_EPSILON);
    		if (error) {
    			KASSERT(error == EWOULDBLOCK);
    			mutex_exit(&res->mutex);
    			return ETIMEDOUT;
    		}
    	}

    	/*
    	 * It's now available to us.  Take ownership of the
    	 * resource, and consume it.
    	 */
    	res->state = BUSY;
    	mutex_exit(&res->mutex);
    	consume(res);

Releasing a resource for the next consumer to use:

    	mutex_enter(&res->mutex);
    	res->state = IDLE;
    	cv_signal(&res->condvar);
    	mutex_exit(&res->mutex);

# CODE REFERENCES

The core of the CV implementation is in sys/kern/kern_condvar.c.

The header file sys/sys/condvar.h describes the public interface.

# SEE ALSO

sigaction(2), membar_ops(3), errno(9), mstohz(9), mutex(9), rwlock(9)

Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel Architecture, Prentice Hall, 2001, ISBN 0-13-022496-0.

# HISTORY

The CV primitives first appeared in NetBSD 5.0. The `cv_timedwaitbt`() and `cv_timedwaitbt_sig`() primitives first appeared in NetBSD 9.0.

September 7, 2023 | NetBSD 11.0