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 . 124.Pp 125When 126.Fn cv_wait , 127.Fn cv_wait_sig , 128.Fn cv_timedwait , 129and 130.Fn cv_timedwait_sig 131unblock, their calling threads are made runnable. 132.Fn cv_timedwait 133and 134.Fn cv_timedwait_sig 135wait for at most 136.Fa timo 137/ 138.Dv HZ 139seconds before being unblocked and returning 140.Er EWOULDBLOCK ; 141otherwise, they return 0. 142.Fn cv_wait_sig 143and 144.Fn cv_timedwait_sig 145return prematurely with a value of 146.Er EINTR 147or 148.Er ERESTART 149if a signal is caught, or 0 if signaled via 150.Fn cv_signal 151or 152.Fn cv_broadcast . 153.Sh RETURN VALUES 154If successful, 155.Fn cv_wait_sig , 156.Fn cv_timedwait , 157and 158.Fn cv_timedwait_sig 159return 0. 160Otherwise, a non-zero error code is returned. 161.Pp 162.Fn cv_wmesg 163returns the description string that was passed to 164.Fn cv_init . 165.Sh ERRORS 166.Fn cv_wait_sig 167and 168.Fn cv_timedwait_sig 169will fail if: 170.Bl -tag -width Er 171.It Bq Er EINTR 172An unmasked signal was caught. 173.It Bq Er ERESTART 174A masked signal was caught. 175.El 176.Pp 177.Fn cv_timedwait 178and 179.Fn cv_timedwait_sig 180will fail if: 181.Bl -tag -width Er 182.It Bq Er EWOULDBLOCK 183Timeout expired. 184.El 185.Sh SEE ALSO 186.Xr msleep 9 , 187.Xr mtx_pool 9 , 188.Xr mutex 9 , 189.Xr sema 9 , 190.Xr sx 9 191