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