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