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 December 11, 2000 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_timedwait , 39.Nm cv_timedwait_sig , 40.Nm cv_signal , 41.Nm cv_broadcast , 42.Nm cv_broadcastpri , 43.Nm cv_wmesg 44.Nd kernel condition variable 45.Sh SYNOPSIS 46.In sys/param.h 47.In sys/proc.h 48.In sys/condvar.h 49.Ft void 50.Fn cv_init "struct cv *cvp" "const char *desc" 51.Ft void 52.Fn cv_destroy "struct cv *cvp" 53.Ft void 54.Fn cv_wait "struct cv *cvp" "struct mtx *mp" 55.Ft int 56.Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp" 57.Ft int 58.Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo" 59.Ft int 60.Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "int timo" 61.Ft void 62.Fn cv_signal "struct cv *cvp" 63.Ft void 64.Fn cv_broadcast "struct cv *cvp" 65.Ft void 66.Fn cv_broadcastpri "struct cv *cvp" "int pri" 67.Ft const char * 68.Fn cv_wmesg "struct cv *cvp" 69.Sh DESCRIPTION 70Condition variables are used in conjunction with mutexes to wait for conditions 71to occur. 72Condition variables are created with 73.Fn cv_init , 74where 75.Fa cvp 76is a pointer to space for a 77.Vt struct cv , 78and 79.Fa desc 80is a pointer to a null-terminated character string that describes the condition 81variable. 82Condition variables are destroyed with 83.Fn cv_destroy . 84Threads wait on condition variables by calling 85.Fn cv_wait , 86.Fn cv_wait_sig , 87.Fn cv_timedwait , 88or 89.Fn cv_timedwait_sig . 90Threads unblock waiters by calling 91.Fn cv_signal 92to unblock one waiter, or 93.Fn cv_broadcast 94or 95.Fn cv_broadcastpri 96to unblock all waiters. 97In addition to waking waiters, 98.Fn cv_broadcastpri 99ensures that all of the waiters have a priority of at least 100.Fa pri 101by raising the priority of any threads that do not. 102.Fn cv_wmesg 103returns the description string of 104.Fa cvp , 105as set by the initial call to 106.Fn cv_init . 107.Pp 108A thread must hold 109.Fa mp 110before calling 111.Fn cv_wait , 112.Fn cv_wait_sig , 113.Fn cv_timedwait , 114or 115.Fn cv_timedwait_sig . 116When a thread waits on a condition, 117.Fa mp 118is atomically released before the thread is blocked, then atomically reacquired 119before the function call returns. 120All waiters must pass the same 121.Fa mp 122in conjunction with 123.Fa cvp . 124A thread must hold 125.Fa mp 126while calling 127.Fn cv_signal , 128.Fn cv_broadcast , 129or 130.Fn cv_broadcastpri 131even though it isn't passed as an argument. 132.Pp 133When 134.Fn cv_wait , 135.Fn cv_wait_sig , 136.Fn cv_timedwait , 137and 138.Fn cv_timedwait_sig 139unblock, their calling threads are made runnable. 140.Fn cv_timedwait 141and 142.Fn cv_timedwait_sig 143wait for at most 144.Fa timo 145/ 146.Dv HZ 147seconds before being unblocked and returning 148.Er EWOULDBLOCK ; 149otherwise, they return 0. 150.Fn cv_wait_sig 151and 152.Fn cv_timedwait_sig 153return prematurely with a value of 154.Er EINTR 155or 156.Er ERESTART 157if a signal is caught, or 0 if signaled via 158.Fn cv_signal 159or 160.Fn cv_broadcast . 161.Sh RETURN VALUES 162If successful, 163.Fn cv_wait_sig , 164.Fn cv_timedwait , 165and 166.Fn cv_timedwait_sig 167return 0. 168Otherwise, a non-zero error code is returned. 169.Pp 170.Fn cv_wmesg 171returns the description string that was passed to 172.Fn cv_init . 173.Sh ERRORS 174.Fn cv_wait_sig 175and 176.Fn cv_timedwait_sig 177will fail if: 178.Bl -tag -width Er 179.It Bq Er EINTR 180An unmasked signal was caught. 181.It Bq Er ERESTART 182A masked signal was caught. 183.El 184.Pp 185.Fn cv_timedwait 186and 187.Fn cv_timedwait_sig 188will fail if: 189.Bl -tag -width Er 190.It Bq Er EWOULDBLOCK 191Timeout expired. 192.El 193.Sh SEE ALSO 194.Xr msleep 9 , 195.Xr mtx_pool 9 , 196.Xr mutex 9 , 197.Xr sema 9 , 198.Xr sx 9 199