Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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.

NetBSD 10.99                   September 7, 2023                  NetBSD 10.99