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.Dd February 19, 2013 28.Dt CONDVAR 9 29.Os 30.Sh NAME 31.Nm condvar , 32.Nm cv_init , 33.Nm cv_destroy , 34.Nm cv_wait , 35.Nm cv_wait_sig , 36.Nm cv_wait_unlock , 37.Nm cv_timedwait , 38.Nm cv_timedwait_sbt , 39.Nm cv_timedwait_sig , 40.Nm cv_timedwait_sig_sbt , 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_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ 64"sbintime_t pr" "int flags" 65.Ft int 66.Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo" 67.Ft int 68.Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ 69"sbintime_t pr" "int flags" 70.Ft void 71.Fn cv_signal "struct cv *cvp" 72.Ft void 73.Fn cv_broadcast "struct cv *cvp" 74.Ft void 75.Fn cv_broadcastpri "struct cv *cvp" "int pri" 76.Ft const char * 77.Fn cv_wmesg "struct cv *cvp" 78.Sh DESCRIPTION 79Condition variables are used in conjunction with mutexes to wait for conditions 80to occur. 81Condition variables are created with 82.Fn cv_init , 83where 84.Fa cvp 85is a pointer to space for a 86.Vt struct cv , 87and 88.Fa desc 89is a pointer to a null-terminated character string that describes the condition 90variable. 91Condition variables are destroyed with 92.Fn cv_destroy . 93Threads wait on condition variables by calling 94.Fn cv_wait , 95.Fn cv_wait_sig , 96.Fn cv_wait_unlock , 97.Fn cv_timedwait , 98or 99.Fn cv_timedwait_sig . 100Threads unblock waiters by calling 101.Fn cv_signal 102to unblock one waiter, or 103.Fn cv_broadcast 104or 105.Fn cv_broadcastpri 106to unblock all waiters. 107In addition to waking waiters, 108.Fn cv_broadcastpri 109ensures that all of the waiters have a priority of at least 110.Fa pri 111by raising the priority of any threads that do not. 112.Fn cv_wmesg 113returns the description string of 114.Fa cvp , 115as set by the initial call to 116.Fn cv_init . 117.Pp 118The 119.Fa lock 120argument is a pointer to either a 121.Xr mutex 9 , 122.Xr rwlock 9 , 123or 124.Xr sx 9 125lock. 126A 127.Xr mutex 9 128argument must be initialized with 129.Dv MTX_DEF 130and not 131.Dv MTX_SPIN . 132A thread must hold 133.Fa lock 134before calling 135.Fn cv_wait , 136.Fn cv_wait_sig , 137.Fn cv_wait_unlock , 138.Fn cv_timedwait , 139or 140.Fn cv_timedwait_sig . 141When a thread waits on a condition, 142.Fa lock 143is atomically released before the thread is blocked, then reacquired 144before the function call returns. 145In addition, the thread will fully drop the 146.Va Giant 147mutex 148(even if recursed) 149while the it is suspended and will reacquire the 150.Va Giant 151mutex before the function returns. 152The 153.Fn cv_wait_unlock 154function does not reacquire the lock before returning. 155Note that the 156.Va Giant 157mutex may be specified as 158.Fa lock . 159However, 160.Va Giant 161may not be used as 162.Fa lock 163for the 164.Fn cv_wait_unlock 165function. 166All waiters must pass the same 167.Fa lock 168in conjunction with 169.Fa cvp . 170.Pp 171When 172.Fn cv_wait , 173.Fn cv_wait_sig , 174.Fn cv_wait_unlock , 175.Fn cv_timedwait , 176and 177.Fn cv_timedwait_sig 178unblock, their calling threads are made runnable. 179.Fn cv_timedwait 180and 181.Fn cv_timedwait_sig 182wait for at most 183.Fa timo 184/ 185.Dv HZ 186seconds before being unblocked and returning 187.Er EWOULDBLOCK ; 188otherwise, they return 0. 189.Fn cv_wait_sig 190and 191.Fn cv_timedwait_sig 192return prematurely with a value of 193.Er EINTR 194or 195.Er ERESTART 196if a signal is caught, or 0 if signaled via 197.Fn cv_signal 198or 199.Fn cv_broadcast . 200.Pp 201.Fn cv_timedwait_sbt 202and 203.Fn cv_timedwait_sig_sbt 204functions take 205.Fa sbt 206argument instead of 207.Fa timo . 208It allows to specify relative or absolute unblock time with higher resolution 209in form of 210.Vt sbintime_t . 211The parameter 212.Fa pr 213allows to specify wanted absolute event precision. 214The parameter 215.Fa flags 216allows to pass additional 217.Fn callout_reset_sbt 218flags. 219.Sh RETURN VALUES 220If successful, 221.Fn cv_wait_sig , 222.Fn cv_timedwait , 223and 224.Fn cv_timedwait_sig 225return 0. 226Otherwise, a non-zero error code is returned. 227.Pp 228.Fn cv_wmesg 229returns the description string that was passed to 230.Fn cv_init . 231.Sh ERRORS 232.Fn cv_wait_sig 233and 234.Fn cv_timedwait_sig 235will fail if: 236.Bl -tag -width Er 237.It Bq Er EINTR 238A signal was caught and the system call should be interrupted. 239.It Bq Er ERESTART 240A signal was caught and the system call should be restarted. 241.El 242.Pp 243.Fn cv_timedwait 244and 245.Fn cv_timedwait_sig 246will fail if: 247.Bl -tag -width Er 248.It Bq Er EWOULDBLOCK 249Timeout expired. 250.El 251.Sh SEE ALSO 252.Xr callout 9 , 253.Xr locking 9 , 254.Xr mtx_pool 9 , 255.Xr mutex 9 , 256.Xr rwlock 9 , 257.Xr sema 9 , 258.Xr sleep 9 , 259.Xr sx 9 260