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