1.\" $NetBSD: condvar.9,v 1.11 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 2006, 2007, 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 26, 2008 31.Dt CONDVAR 9 32.Os 33.Sh NAME 34.Nm cv , 35.Nm condvar , 36.Nm cv_init , 37.Nm cv_destroy , 38.Nm cv_wait , 39.Nm cv_wait_sig , 40.Nm cv_timedwait , 41.Nm cv_timedwait_sig , 42.Nm cv_signal , 43.Nm cv_broadcast , 44.Nm cv_has_waiters 45.Nd condition variables 46.Sh SYNOPSIS 47.In sys/condvar.h 48.Ft void 49.Fn cv_init "kcondvar_t *cv" "const char *wmesg" 50.Ft void 51.Fn cv_destroy "kcondvar_t *cv" 52.Ft void 53.Fn cv_wait "kcondvar_t *cv" "kmutex_t *mtx" 54.Ft int 55.Fn cv_wait_sig "kcondvar_t *cv" "kmutex_t *mtx" 56.Ft int 57.Fn cv_timedwait "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" 58.Ft int 59.Fn cv_timedwait_sig "kcondvar_t *cv" "kmutex_t *mtx" "int ticks" 60.Ft void 61.Fn cv_signal "kcondvar_t *cv" 62.Ft void 63.Fn cv_broadcast "kcondvar_t *cv" 64.Ft bool 65.Fn cv_has_waiters "kcondvar_t *cv" 66.Sh DESCRIPTION 67Condition variables (CVs) are used in the kernel to synchronize access 68to resources that are limited (for example, memory) and to wait for 69pending I/O operations to complete. 70.Pp 71The 72.Vt kcondvar_t 73type provides storage for the CV object. 74This should be treated as an opaque object and not examined directly by 75consumers. 76.Sh FUNCTIONS 77.Bl -tag -width abcd 78.It Fn cv_init "cv" "wmesg" 79.Pp 80Initialize a CV for use. 81No other operations can be performed on the CV until it has been initialized. 82.Pp 83The 84.Fa wmesg 85argument specifies a string of no more than 8 characters that describes 86the resource or condition associated with the CV. 87The kernel does not use this argument directly but makes it available for 88utilities such as 89.Xr ps 1 90to display. 91.It Fn cv_destroy "cv" 92.Pp 93Release resources used by a CV. 94The CV must not be in use when it is destroyed, and must not be used afterwards. 95.It Fn cv_wait "cv" "mtx" 96.Pp 97Cause the current LWP to wait non-interruptably for access to a resource, 98or for an I/O operation to complete. 99The LWP will resume execution when awoken by another thread using 100.Fn cv_signal 101or 102.Fn cv_broadcast . 103.Pp 104.Fa mtx 105specifies a kernel mutex to be used as an interlock, and must be held by the 106calling LWP on entry to 107.Fn cv_wait . 108It will be released once the LWP has prepared to sleep, and will be reacquired 109before 110.Fn cv_wait 111returns. 112.Pp 113A small window exists between testing for availability of a resource and 114waiting for the resource with 115.Fn cv_wait , 116in which the resource may become available again. 117The interlock is used to guarentee that the resource will not be signalled 118as available until the calling LWP has begun to wait for it. 119.Pp 120Non-interruptable waits have the potential to deadlock the system, and so must 121be kept short (typically, under one second). 122.It Fn cv_wait_sig "cv" "mtx" 123.Pp 124As per 125.Fn cv_wait , 126but causes the current LWP to wait interruptably. 127If the LWP recieves a signal, or is interrupted by another condition such 128as its containing process exiting, the wait is ended early and an error 129code returned. 130.Pp 131If 132.Fn cv_wait_sig 133returns as a result of a signal, the return value is 134.Er ERESTART 135if the signal 136has the 137.Dv SA_RESTART 138property. 139If awoken normally, the value is zero, and 140.Er EINTR 141under all other conditions. 142.It Fn cv_timedwait "cv" "mtx" "ticks" 143.Pp 144As per 145.Fn cv_wait , 146but will return early if a timeout specified by the 147.Fa ticks 148argument expires. 149.Pp 150.Fa ticks 151is an architecture and system dependent value related to the number of 152clock interrupts per second. 153See 154.Xr hz 9 155for details. 156The 157.Xr mstohz 9 158macro can be used to convert a timeout expressed in milliseconds to 159one suitable for 160.Fn cv_timedwait . 161If the 162.Fa ticks 163argument is zero, 164.Fn cv_timedwait 165behaves exactly like 166.Fn cv_wait . 167.Pp 168If the timeout expires before the LWP is awoken, the return value is 169.Er EWOULDBLOCK . 170If awoken normally, the return value is zero. 171.It Fn cv_timedwait_sig "cv" "mtx" "ticks" 172.Pp 173As per 174.Fn cv_wait_sig , 175but also accepts a timeout value and will return 176.Er EWOULDBLOCK 177if the timeout expires. 178.It Fn cv_signal "cv" 179.Pp 180Awaken one LWP (potentially among many) that is waiting on the specified 181condition variable. 182The mutex passed to the wait function 183.Po Fa mtx Pc 184must also be held when calling 185.Fn cv_signal . 186.Pp 187(Note that 188.Fn cv_signal 189is erroneously named in that it does not send a signal in the traditional 190sense to LWPs waiting on a CV.) 191.It Fn cv_broadcast "cv" 192.Pp 193Awaken all LWPs waiting on the specified condition variable. 194The mutex passed to the wait function 195.Po Fa mtx Pc 196must also be held when calling 197.Fn cv_broadcast . 198.It Fn cv_has_waiters "cv" 199.Pp 200Return 201.Dv true 202if one or more LWPs are waiting on the specified condition variable. 203.Pp 204.Fn cv_has_waiters 205cannot test reliably for interruptable waits. 206It should only be used to test for non-interruptable waits 207made using 208.Fn cv_wait . 209.Pp 210.Fn cv_has_waiters 211should only be used when making diagnostic assertions, and must 212be called while holding the interlocking mutex passed to 213.Fn cv_wait . 214.El 215.Sh EXAMPLES 216.Bd -literal 217Consuming a resource: 218 219 /* 220 * Lock the resource. Its mutex will also serve as the 221 * interlock. 222 */ 223 mutex_enter(\*[Am]res-\*[Gt]mutex); 224 225 /* 226 * Wait for the resource to become available. 227 */ 228 while (res-\*[Gt]state == BUSY) 229 cv_wait(\*[Am]res-\*[Gt]condvar, \*[Am]res-\*[Gt]mutex); 230 231 /* 232 * It's now available to us. Take ownership of the 233 * resource, and consume it. 234 */ 235 res-\*[Gt]state = BUSY; 236 mutex_exit(\*[Am]res-\*[Gt]mutex); 237 consume(res); 238 239Releasing a resource for the next consumer to use: 240 241 mutex_enter(\*[Am]res-\*[Gt]mutex); 242 res-\*[Gt]state = IDLE; 243 cv_signal(\*[Am]res-\*[Gt]condvar); 244 mutex_exit(\*[Am]res-\*[Gt]mutex); 245.Ed 246.Sh CODE REFERENCES 247This section describes places within the 248.Nx 249source tree where code implementing condition variables can be found. 250All pathnames are relative to 251.Pa /usr/src . 252.Pp 253The core of the CV implementation is in 254.Pa sys/kern/kern_condvar.c . 255.Pp 256The header file 257.Pa sys/sys/condvar.h 258describes the public interface. 259.Sh SEE ALSO 260.Xr sigaction 2 , 261.Xr errno 9 , 262.Xr mb 9 , 263.Xr mstohz 9 , 264.Xr mutex 9 , 265.Xr rwlock 9 266.Pp 267.Rs 268.%A Jim Mauro 269.%A Richard McDougall 270.%T Solaris Internals: Core Kernel Architecture 271.%I Prentice Hall 272.%D 2001 273.%O ISBN 0-13-022496-0 274.Re 275.Sh HISTORY 276The CV primitives first appeared in 277.Nx 5.0 . 278