Copyright (c) 2006, 2007, 2008 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Andrew Doran.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd January 26, 2008 .Dt CONDVAR 9 .Os .Sh NAME .Nm cv , .Nm condvar , .Nm cv_init , .Nm cv_destroy , .Nm cv_wait , .Nm cv_wait_sig , .Nm cv_timedwait , .Nm cv_timedwait_sig , .Nm cv_signal , .Nm cv_broadcast , .Nm cv_has_waiters .Nd condition variables .Sh SYNOPSIS n sys/condvar.h .Ft void .Fn cv_init "kcondvar_t *cv" "const char *wmesg" .Ft void .Fn cv_destroy "kcondvar_t *cv" .Ft void .Fn cv_wait "kcondvar_t *cv" "kmutex_t *mtx" .Ft int .Fn cv_wait_sig "kcondvar_t *cv" "kmutex_t *mtx" .Ft int .Fn cv_timedwait "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" .Ft int .Fn cv_timedwait_sig "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" .Ft void .Fn cv_signal "kcondvar_t *cv" .Ft void .Fn cv_broadcast "kcondvar_t *cv" .Ft bool .Fn cv_has_waiters "kcondvar_t *cv" .Sh 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.
p The .Vt kcondvar_t type provides storage for the CV object. This should be treated as an opaque object and not examined directly by consumers. .Sh FUNCTIONS l -tag -width abcd t Fn cv_init "cv" "wmesg"
p Initialize a CV for use. No other operations can be performed on the CV until it has been initialized.
p The .Fa 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 .Xr ps 1 to display. t Fn cv_destroy "cv"
p Release resources used by a CV. The CV must not be in use when it is destroyed, and must not be used afterwards. t Fn cv_wait "cv" "mtx"
p 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 .Fn cv_signal or .Fn cv_broadcast .
p .Fa mtx specifies a kernel mutex to be used as an interlock, and must be held by the calling LWP on entry to .Fn cv_wait . It will be released once the LWP has prepared to sleep, and will be reacquired before .Fn cv_wait returns.
p A small window exists between testing for availability of a resource and waiting for the resource with .Fn cv_wait , in which the resource may become available again. The interlock is used to guarentee that the resource will not be signalled as available until the calling LWP has begun to wait for it.
p Non-interruptable waits have the potential to deadlock the system, and so must be kept short (typically, under one second). t Fn cv_wait_sig "cv" "mtx"
p As per .Fn cv_wait , but causes the current LWP to wait interruptably. If the LWP recieves a signal, or is interrupted by another condition such as its containing process exiting, the wait is ended early and an error code returned.
p If .Fn cv_wait_sig returns as a result of a signal, the return value is .Er ERESTART if the signal has the .Dv SA_RESTART property. If awoken normally, the value is zero, and .Er EINTR under all other conditions. t Fn cv_timedwait "cv" "mtx" "ticks"
p As per .Fn cv_wait , but will return early if a timeout specified by the .Fa ticks argument expires.
p .Fa ticks is an architecture and system dependent value related to the number of clock interrupts per second. See .Xr hz 9 for details. The .Xr mstohz 9 macro can be used to convert a timeout expressed in milliseconds to one suitable for .Fn cv_timedwait . If the .Fa ticks argument is zero, .Fn cv_timedwait behaves exactly like .Fn cv_wait .
p If the timeout expires before the LWP is awoken, the return value is .Er EWOULDBLOCK . If awoken normally, the return value is zero. t Fn cv_timedwait_sig "cv" "mtx" "ticks"
p As per .Fn cv_wait_sig , but also accepts a timeout value and will return .Er EWOULDBLOCK if the timeout expires. t Fn cv_signal "cv"
p Awaken one LWP (potentially among many) that is waiting on the specified condition variable. The mutex passed to the wait function
o Fa mtx Pc must also be held when calling .Fn cv_signal .
p (Note that .Fn cv_signal is erroneously named in that it does not send a signal in the traditional sense to LWPs waiting on a CV.) t Fn cv_broadcast "cv"
p Awaken all LWPs waiting on the specified condition variable. The mutex passed to the wait function
o Fa mtx Pc must also be held when calling .Fn cv_broadcast . t Fn cv_has_waiters "cv"
p Return .Dv true if one or more LWPs are waiting on the specified condition variable.
p .Fn cv_has_waiters cannot test reliably for interruptable waits. It should only be used to test for non-interruptable waits made using .Fn cv_wait .
p .Fn cv_has_waiters should only be used when making diagnostic assertions, and must be called while holding the interlocking mutex passed to .Fn cv_wait . .El .Sh EXAMPLES d -literal Consuming a resource: /* * Lock the resource. Its mutex will also serve as the * interlock. */ mutex_enter(\*[Am]res-\*[Gt]mutex); /* * Wait for the resource to become available. */ while (res-\*[Gt]state == BUSY) cv_wait(\*[Am]res-\*[Gt]condvar, \*[Am]res-\*[Gt]mutex); /* * It's now available to us. Take ownership of the * resource, and consume it. */ res-\*[Gt]state = BUSY; mutex_exit(\*[Am]res-\*[Gt]mutex); consume(res); Releasing a resource for the next consumer to use: mutex_enter(\*[Am]res-\*[Gt]mutex); res-\*[Gt]state = IDLE; cv_signal(\*[Am]res-\*[Gt]condvar); mutex_exit(\*[Am]res-\*[Gt]mutex); .Ed .Sh CODE REFERENCES This section describes places within the .Nx source tree where code implementing condition variables can be found. All pathnames are relative to
p The core of the CV implementation is in
a sys/kern/kern_condvar.c .
p The header file
a sys/sys/condvar.h describes the public interface. .Sh SEE ALSO .Xr sigaction 2 , .Xr errno 9 , .Xr mb 9 , .Xr mstohz 9 , .Xr mutex 9 , .Xr rwlock 9
p .Rs .%A Jim Mauro .%A Richard McDougall .%T Solaris Internals: Core Kernel Architecture .%I Prentice Hall .%D 2001 .%O ISBN 0-13-022496-0 .Re .Sh HISTORY The CV primitives first appeared in .Nx 5.0 .
Indexes created Thu Oct 23 22:10:10 GMT 2025