| CONDVAR(9) | Kernel Developer's Manual | CONDVAR(9) | 
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
  —
#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
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 DIAGNOSTICKernels compiled with the DIAGNOSTIC
        option perform basic sanity checks on CV operations.
options LOCKDEBUGKernels compiled with the LOCKDEBUG
        option perform potentially CPU intensive sanity checks on CV
      operations.
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) must also be held when calling
        cv_signal().
(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.
        The mutex passed to the wait function (mtx) must
        also be held when calling cv_broadcast().
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().
	/*
	 * 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);
The header file sys/sys/condvar.h describes the public interface.
Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel Architecture, Prentice Hall, 2001, ISBN 0-13-022496-0.
cv_timedwaitbt() and
  cv_timedwaitbt_sig() primitives first appeared in
  NetBSD 9.0.
| May 2, 2020 | NetBSD 10.0 |