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 February 1, 2006 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" "struct mtx *mp" 56.Ft int 57.Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp" 58.Ft void 59.Fn cv_wait_unlock "struct cv *cvp" "struct mtx *mp" 60.Ft int 61.Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo" 62.Ft int 63.Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "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 112A thread must hold 113.Fa mp 114before calling 115.Fn cv_wait , 116.Fn cv_wait_sig , 117.Fn cv_wait_unlock , 118.Fn cv_timedwait , 119or 120.Fn cv_timedwait_sig . 121When a thread waits on a condition, 122.Fa mp 123is atomically released before the thread is blocked, then reacquired 124before the function call returns. 125The 126.Fn cv_wait_unlock 127function does not reacquire the lock before returning. 128All waiters must pass the same 129.Fa mp 130in conjunction with 131.Fa cvp . 132.Pp 133When 134.Fn cv_wait , 135.Fn cv_wait_sig , 136.Fn cv_wait_unlock , 137.Fn cv_timedwait , 138and 139.Fn cv_timedwait_sig 140unblock, their calling threads are made runnable. 141.Fn cv_timedwait 142and 143.Fn cv_timedwait_sig 144wait for at most 145.Fa timo 146/ 147.Dv HZ 148seconds before being unblocked and returning 149.Er EWOULDBLOCK ; 150otherwise, they return 0. 151.Fn cv_wait_sig 152and 153.Fn cv_timedwait_sig 154return prematurely with a value of 155.Er EINTR 156or 157.Er ERESTART 158if a signal is caught, or 0 if signaled via 159.Fn cv_signal 160or 161.Fn cv_broadcast . 162.Sh RETURN VALUES 163If successful, 164.Fn cv_wait_sig , 165.Fn cv_timedwait , 166and 167.Fn cv_timedwait_sig 168return 0. 169Otherwise, a non-zero error code is returned. 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 181A signal was caught and the system call should be interrupted. 182.It Bq Er ERESTART 183A signal was caught and the system call should be restarted. 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 mtx_pool 9 , 196.Xr mutex 9 , 197.Xr rwlock 9 , 198.Xr sema 9 , 199.Xr sleep 9 , 200.Xr sx 9 201