1.\" 2.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 25.\" DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd June 5, 2007 30.Dt CONDVAR 9 31.Os 32.Sh NAME 33.Nm condvar , 34.Nm cv_init , 35.Nm cv_destroy , 36.Nm cv_wait , 37.Nm cv_wait_sig , 38.Nm cv_wait_unlock , 39.Nm cv_timedwait , 40.Nm cv_timedwait_sig , 41.Nm cv_signal , 42.Nm cv_broadcast , 43.Nm cv_broadcastpri , 44.Nm cv_wmesg 45.Nd kernel condition variable 46.Sh SYNOPSIS 47.In sys/param.h 48.In sys/proc.h 49.In sys/condvar.h 50.Ft void 51.Fn cv_init "struct cv *cvp" "const char *desc" 52.Ft void 53.Fn cv_destroy "struct cv *cvp" 54.Ft void 55.Fn cv_wait "struct cv *cvp" "lock" 56.Ft int 57.Fn cv_wait_sig "struct cv *cvp" "lock" 58.Ft void 59.Fn cv_wait_unlock "struct cv *cvp" "lock" 60.Ft int 61.Fn cv_timedwait "struct cv *cvp" "lock" "int timo" 62.Ft int 63.Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo" 64.Ft void 65.Fn cv_signal "struct cv *cvp" 66.Ft void 67.Fn cv_broadcast "struct cv *cvp" 68.Ft void 69.Fn cv_broadcastpri "struct cv *cvp" "int pri" 70.Ft const char * 71.Fn cv_wmesg "struct cv *cvp" 72.Sh DESCRIPTION 73Condition variables are used in conjunction with mutexes to wait for conditions 74to occur. 75Condition variables are created with 76.Fn cv_init , 77where 78.Fa cvp 79is a pointer to space for a 80.Vt struct cv , 81and 82.Fa desc 83is a pointer to a null-terminated character string that describes the condition 84variable. 85Condition variables are destroyed with 86.Fn cv_destroy . 87Threads wait on condition variables by calling 88.Fn cv_wait , 89.Fn cv_wait_sig , 90.Fn cv_wait_unlock , 91.Fn cv_timedwait , 92or 93.Fn cv_timedwait_sig . 94Threads unblock waiters by calling 95.Fn cv_signal 96to unblock one waiter, or 97.Fn cv_broadcast 98or 99.Fn cv_broadcastpri 100to unblock all waiters. 101In addition to waking waiters, 102.Fn cv_broadcastpri 103ensures that all of the waiters have a priority of at least 104.Fa pri 105by raising the priority of any threads that do not. 106.Fn cv_wmesg 107returns the description string of 108.Fa cvp , 109as set by the initial call to 110.Fn cv_init . 111.Pp 112The 113.Fa lock 114argument is a pointer to either a 115.Xr mutex 9 , 116.Xr rwlock 9 , 117or 118.Xr sx 9 119lock. 120A 121.Xr mutex 9 122argument must be initialized with 123.Dv MTX_DEF 124and not 125.Dv MTX_SPIN . 126A thread must hold 127.Fa lock 128before calling 129.Fn cv_wait , 130.Fn cv_wait_sig , 131.Fn cv_wait_unlock , 132.Fn cv_timedwait , 133or 134.Fn cv_timedwait_sig . 135When a thread waits on a condition, 136.Fa lock 137is atomically released before the thread is blocked, then reacquired 138before the function call returns. 139In addition, the thread will fully drop the 140.Va Giant 141mutex 142(even if recursed) 143while the it is suspended and will reacquire the 144.Va Giant 145mutex before the function returns. 146The 147.Fn cv_wait_unlock 148function does not reacquire the lock before returning. 149Note that the 150.Va Giant 151mutex may be specified as 152.Fa lock . 153However, 154.Va Giant 155may not be used as 156.Fa lock 157for the 158.Fn cv_wait_unlock 159function. 160All waiters must pass the same 161.Fa lock 162in conjunction with 163.Fa cvp . 164.Pp 165When 166.Fn cv_wait , 167.Fn cv_wait_sig , 168.Fn cv_wait_unlock , 169.Fn cv_timedwait , 170and 171.Fn cv_timedwait_sig 172unblock, their calling threads are made runnable. 173.Fn cv_timedwait 174and 175.Fn cv_timedwait_sig 176wait for at most 177.Fa timo 178/ 179.Dv HZ 180seconds before being unblocked and returning 181.Er EWOULDBLOCK ; 182otherwise, they return 0. 183.Fn cv_wait_sig 184and 185.Fn cv_timedwait_sig 186return prematurely with a value of 187.Er EINTR 188or 189.Er ERESTART 190if a signal is caught, or 0 if signaled via 191.Fn cv_signal 192or 193.Fn cv_broadcast . 194.Sh RETURN VALUES 195If successful, 196.Fn cv_wait_sig , 197.Fn cv_timedwait , 198and 199.Fn cv_timedwait_sig 200return 0. 201Otherwise, a non-zero error code is returned. 202.Pp 203.Fn cv_wmesg 204returns the description string that was passed to 205.Fn cv_init . 206.Sh ERRORS 207.Fn cv_wait_sig 208and 209.Fn cv_timedwait_sig 210will fail if: 211.Bl -tag -width Er 212.It Bq Er EINTR 213A signal was caught and the system call should be interrupted. 214.It Bq Er ERESTART 215A signal was caught and the system call should be restarted. 216.El 217.Pp 218.Fn cv_timedwait 219and 220.Fn cv_timedwait_sig 221will fail if: 222.Bl -tag -width Er 223.It Bq Er EWOULDBLOCK 224Timeout expired. 225.El 226.Sh SEE ALSO 227.Xr locking 9 , 228.Xr mtx_pool 9 , 229.Xr mutex 9 , 230.Xr rwlock 9 , 231.Xr sema 9 , 232.Xr sleep 9 , 233.Xr sx 9 234