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. 139The 140.Fn cv_wait_unlock 141function does not reacquire the lock before returning. 142All waiters must pass the same 143.Fa lock 144in conjunction with 145.Fa cvp . 146.Pp 147When 148.Fn cv_wait , 149.Fn cv_wait_sig , 150.Fn cv_wait_unlock , 151.Fn cv_timedwait , 152and 153.Fn cv_timedwait_sig 154unblock, their calling threads are made runnable. 155.Fn cv_timedwait 156and 157.Fn cv_timedwait_sig 158wait for at most 159.Fa timo 160/ 161.Dv HZ 162seconds before being unblocked and returning 163.Er EWOULDBLOCK ; 164otherwise, they return 0. 165.Fn cv_wait_sig 166and 167.Fn cv_timedwait_sig 168return prematurely with a value of 169.Er EINTR 170or 171.Er ERESTART 172if a signal is caught, or 0 if signaled via 173.Fn cv_signal 174or 175.Fn cv_broadcast . 176.Sh RETURN VALUES 177If successful, 178.Fn cv_wait_sig , 179.Fn cv_timedwait , 180and 181.Fn cv_timedwait_sig 182return 0. 183Otherwise, a non-zero error code is returned. 184.Pp 185.Fn cv_wmesg 186returns the description string that was passed to 187.Fn cv_init . 188.Sh ERRORS 189.Fn cv_wait_sig 190and 191.Fn cv_timedwait_sig 192will fail if: 193.Bl -tag -width Er 194.It Bq Er EINTR 195A signal was caught and the system call should be interrupted. 196.It Bq Er ERESTART 197A signal was caught and the system call should be restarted. 198.El 199.Pp 200.Fn cv_timedwait 201and 202.Fn cv_timedwait_sig 203will fail if: 204.Bl -tag -width Er 205.It Bq Er EWOULDBLOCK 206Timeout expired. 207.El 208.Sh SEE ALSO 209.Xr locking 9 , 210.Xr mtx_pool 9 , 211.Xr mutex 9 , 212.Xr rwlock 9 , 213.Xr sema 9 , 214.Xr sleep 9 , 215.Xr sx 9 216