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 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.
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. The CV must not be in use when it is destroyed, and 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_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)Similar to cv_timedwait
() and
cv_timedwait_sig
(), but bt
is decremented in place with the amount of time actually waited, and on
return contains the amount of time remaining, possibly negative if the
timeout expired.
The hint epsilon 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 (potentially among many) that is waiting on the
specified condition variable. 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 * alloted time, return an error. */ struct bintime timeout = { .sec = 5, .frac = 0 }; const struct bintime epsilon = { .sec = 1, .frac = 0 }; while (res->state == BUSY) { error = cv_timedwaitbt(&res->condvar, \ &res->mutex, &timeout, &epsilon); if (error) { KASSERT(error == EWOULDBLOCK); if (res->state != BUSY) break; 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.
November 12, 2017 | NetBSD 9.0 |