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 August 11, 2011 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 100and discards the 101.Fa pri 102parameter. 103.Pp 104A thread must hold 105.Fa l 106before calling 107.Fn cv_wait , 108.Fn cv_wait_sig , 109.Fn cv_timedwait , 110or 111.Fn cv_timedwait_sig . 112When a thread waits on a condition, 113.Fa l 114is atomically released before the thread is blocked, then atomically reacquired 115before the function call returns. 116All waiters must pass the same 117.Fa l 118in conjunction with 119.Fa cvp . 120.Pp 121When 122.Fn cv_wait , 123.Fn cv_wait_sig , 124.Fn cv_timedwait , 125and 126.Fn cv_timedwait_sig 127unblock, their calling threads are made runnable. 128.Fn cv_timedwait 129and 130.Fn cv_timedwait_sig 131wait for at most 132.Fa timo 133/ hz seconds before being unblocked and returning 134.Er EWOULDBLOCK ; 135otherwise, they return 0. 136.Fn cv_wait_sig 137and 138.Fn cv_timedwait_sig 139return prematurely with a value of 140.Er EINTR 141or 142.Er ERESTART 143if a signal is caught, or 0 if signaled via 144.Fn cv_signal 145or 146.Fn cv_broadcast . 147.Sh IMPLEMENTATION NOTES 148Condition variables exist primarily for code imported from other systems; for 149.Dx 150code, the 151.Fn tsleep 152/ 153.Fn wakeup 154family of functions should be used instead. 155.Pp 156Condition variables can currently only release 157.Xr lockmgr 9 158locks. 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.Sh FILES 168Condition variables are implemented in 169.Pa /sys/kern/kern_condvar.c . 170The public interface and structure is found in 171.Pa /sys/sys/condvar.h . 172.Sh SEE ALSO 173.Xr locking 9 , 174.Xr lockmgr 9 , 175.Xr tsleep 9 176.Sh HISTORY 177Condition variables appeared in 178.Dx 2.7 . 179.Sh AUTHORS 180This manual page was written by 181.An Jason Evans 182for 183.Fx . 184