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_waitq_remove , 43.Nm cv_waitq_empty , 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" "struct mtx *mp" 56.Ft int 57.Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp" 58.Ft int 59.Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo" 60.Ft int 61.Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "int timo" 62.Ft void 63.Fn cv_signal "struct cv *cvp" 64.Ft void 65.Fn cv_broadcast "struct cv *cvp" 66.Ft void 67.Fn cv_waitq_remove "struct thread *td" 68.Ft int 69.Fn cv_waitq_empty "struct cv *cvp" 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_timedwait , 91or 92.Fn cv_timedwait_sig . 93Threads unblock waiters by calling 94.Fn cv_signal 95to unblock one waiter, or 96.Fn cv_broadcast 97to unblock all waiters. 98.Fn cv_waitq_remove 99removes a waiting thread from a condition variable wait queue, if it is on one. 100.Fn cv_waitq_empty 101reports whether there are any waiters on 102.Fa cvp . 103.Fn cv_wmesg 104returns the description string of 105.Fa cvp , 106as set by the initial call to 107.Fn cv_init . 108.Pp 109A thread must hold 110.Fa mp 111before calling 112.Fn cv_wait , 113.Fn cv_wait_sig , 114.Fn cv_timedwait , 115or 116.Fn cv_timedwait_sig . 117When a thread waits on a condition, 118.Fa mp 119is atomically released before the thread is blocked, then atomically reacquired 120before the function call returns. 121All waiters must pass the same 122.Fa mp 123in conjunction with 124.Fa cvp . 125A thread must hold 126.Fa mp 127while calling 128.Fn cv_signal 129or 130.Fn cv_broadcast , 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_waitq_empty 171returns non-zero if there are no threads on the wait queue; 0 otherwise. 172.Pp 173.Fn cv_wmesg 174returns the description string that was passed to 175.Fn cv_init . 176.Sh ERRORS 177.Fn cv_wait_sig 178and 179.Fn cv_timedwait_sig 180will fail if: 181.Bl -tag -width Er 182.It Bq Er EINTR 183An unmasked signal was caught. 184.It Bq Er ERESTART 185A masked signal was caught. 186.El 187.Pp 188.Fn cv_timedwait 189and 190.Fn cv_timedwait_sig 191will fail if: 192.Bl -tag -width Er 193.It Bq Er EWOULDBLOCK 194Timeout expired. 195.El 196.Sh SEE ALSO 197.Xr msleep 9 , 198.Xr mtx_pool 9 , 199.Xr mutex 9 , 200.Xr sema 9 , 201.Xr sx 9 202