1.\" 2.\" Copyright (C) 2010 The DragonFly Project. All rights reserved. 3.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/condvar.9,v 1.11 2004/11/08 18:15:11 jhb Exp $ 29.\" 30.Dd April 16, 2010 31.Dt CONDVAR 9 32.Os 33.Sh NAME 34.Nm condvar , 35.Nm cv_init , 36.Nm cv_destroy , 37.Nm cv_wait , 38.Nm cv_wait_sig , 39.Nm cv_timedwait , 40.Nm cv_timedwait_sig , 41.Nm cv_signal , 42.Nm cv_broadcast , 43.Nm cv_broadcastpri 44.Nd kernel condition variable 45.Sh SYNOPSIS 46.In sys/param.h 47.In sys/systm.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 lock *l" 55.Ft int 56.Fn cv_wait_sig "struct cv *cvp" "struct lock *l" 57.Ft int 58.Fn cv_timedwait "struct cv *cvp" "struct lock *l" "int timo" 59.Ft int 60.Fn cv_timedwait_sig "struct cv *cvp" "struct lock *l" "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.Sh DESCRIPTION 68Condition variables are used in conjunction with locks to wait for conditions 69to occur. 70Condition variables are created with 71.Fn cv_init , 72where 73.Fa cvp 74is a pointer to space for a 75.Vt struct cv , 76and 77.Fa desc 78is a pointer to a null-terminated character string that describes the condition 79variable. 80Condition variables are destroyed with 81.Fn cv_destroy . 82Threads wait on condition variables by calling 83.Fn cv_wait , 84.Fn cv_wait_sig , 85.Fn cv_timedwait , 86or 87.Fn cv_timedwait_sig . 88Threads unblock waiters by calling 89.Fn cv_signal 90to unblock one waiter, or 91.Fn cv_broadcast 92or 93.Fn cv_broadcastpri 94to unblock all waiters. 95.Fn cv_broadcastpri 96is a synonym for 97.Fn cv_broadcast 98in 99.Dx . 100.Pp 101A thread must hold 102.Fa l 103before calling 104.Fn cv_wait , 105.Fn cv_wait_sig , 106.Fn cv_timedwait , 107or 108.Fn cv_timedwait_sig . 109When a thread waits on a condition, 110.Fa l 111is atomically released before the thread is blocked, then atomically reacquired 112before the function call returns. 113All waiters must pass the same 114.Fa l 115in conjunction with 116.Fa cvp . 117.Pp 118When 119.Fn cv_wait , 120.Fn cv_wait_sig , 121.Fn cv_timedwait , 122and 123.Fn cv_timedwait_sig 124unblock, their calling threads are made runnable. 125.Fn cv_timedwait 126and 127.Fn cv_timedwait_sig 128wait for at most 129.Fa timo 130seconds before being unblocked and returning 131.Er EWOULDBLOCK ; 132otherwise, they return 0. 133.Fn cv_wait_sig 134and 135.Fn cv_timedwait_sig 136return prematurely with a value of 137.Er EINTR 138or 139.Er ERESTART 140if a signal is caught, or 0 if signaled via 141.Fn cv_signal 142or 143.Fn cv_broadcast . 144.Sh IMPLEMENTATION NOTES 145Condition variables exist primarily for code imported from other systems; for 146.Dx 147code, the 148.Fn tsleep / 149.Fn wakeup 150family of functions should be used instead. 151.Pp 152Condition variables can currently only release 153.Xr lockmgr 9 154locks. 155.Sh RETURN VALUES 156If successful, 157.Fn cv_wait_sig , 158.Fn cv_timedwait , 159and 160.Fn cv_timedwait_sig 161return 0. 162Otherwise, a non-zero error code is returned. 163.Sh FILES 164Condition variables are implemented in 165.Pa /sys/kern/kern_condvar.c . 166The public interface and structure is found in 167.Pa /sys/sys/condvar.h . 168.Sh SEE ALSO 169.Xr lockmgr 9 , 170.Xr tsleep 9 171.Sh HISTORY 172Condition variables appeared in 173.Dx 2.7 . 174.Sh AUTHORS 175This manual page was written by 176.An Jason Evans 177for 178.Fx . 179