NAME
cv,
condvar,
cv_init,
cv_destroy,
cv_wait,
cv_wait_sig,
cv_timedwait,
cv_timedwait_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);
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. 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_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().
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.
*/
while (res->state == BUSY)
cv_wait(&res->condvar, &res->mutex);
/*
* 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),
errno(9),
mb(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.