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 June 29, 2018 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_mtx_wait , 42.Nm cv_mtx_wait_sig , 43.Nm cv_mtx_timedwait , 44.Nm cv_mtx_timedwait_sig , 45.Nm cv_signal , 46.Nm cv_broadcast , 47.Nm cv_broadcastpri 48.Nd kernel condition variable 49.Sh SYNOPSIS 50.In sys/param.h 51.In sys/systm.h 52.In sys/condvar.h 53.Ft void 54.Fn cv_init "struct cv *cvp" "const char *desc" 55.Ft void 56.Fn cv_destroy "struct cv *cvp" 57.Ft void 58.Fn cv_wait "struct cv *cvp" "struct lock *l" 59.Ft int 60.Fn cv_wait_sig "struct cv *cvp" "struct lock *l" 61.Ft int 62.Fn cv_timedwait "struct cv *cvp" "struct lock *l" "int timo" 63.Ft int 64.Fn cv_timedwait_sig "struct cv *cvp" "struct lock *l" "int timo" 65.Ft void 66.Fn cv_mtx_wait "struct cv *cvp" "struct mtx *m" 67.Ft int 68.Fn cv_mtx_wait_sig "struct cv *cvp" "struct mtx *m" 69.Ft int 70.Fn cv_mtx_timedwait "struct cv *cvp" "struct mtx *m" "int timo" 71.Ft int 72.Fn cv_mtx_timedwait_sig "struct cv *cvp" "struct mtx *m" "int timo" 73.Ft void 74.Fn cv_signal "struct cv *cvp" 75.Ft void 76.Fn cv_broadcast "struct cv *cvp" 77.Ft void 78.Fn cv_broadcastpri "struct cv *cvp" "int pri" 79.Sh DESCRIPTION 80Condition variables are used in conjunction with locks to wait for conditions 81to occur. 82Condition variables are created with 83.Fn cv_init , 84where 85.Fa cvp 86is a pointer to space for a 87.Vt struct cv , 88and 89.Fa desc 90is a pointer to a null-terminated character string that describes the condition 91variable. 92Condition variables are destroyed with 93.Fn cv_destroy . 94Threads wait on condition variables by calling 95.Fn cv_wait , 96.Fn cv_wait_sig , 97.Fn cv_timedwait , 98or 99.Fn cv_timedwait_sig . 100Threads unblock waiters by calling 101.Fn cv_signal 102to unblock one waiter, or 103.Fn cv_broadcast 104or 105.Fn cv_broadcastpri 106to unblock all waiters. 107.Fn cv_broadcastpri 108is a synonym for 109.Fn cv_broadcast 110in 111.Dx 112and discards the 113.Fa pri 114parameter. 115.Pp 116A thread must hold 117.Fa l 118before calling 119.Fn cv_wait , 120.Fn cv_wait_sig , 121.Fn cv_timedwait , 122or 123.Fn cv_timedwait_sig . 124When a thread waits on a condition, 125.Fa l 126is atomically released before the thread is blocked, then atomically reacquired 127before the function call returns. 128All waiters must pass the same 129.Fa l 130in conjunction with 131.Fa cvp . 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/ hz seconds 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.Pp 160.Fn cv_mtx_wait , 161.Fn cv_mtx_wait_sig , 162.Fn cv_mtx_timedwait , 163and 164.Fn cv_mtx_timedwait_sig 165work the same as 166.Fn cv_wait , 167.Fn cv_wait_sig , 168.Fn cv_timedwait , 169and 170.Fn cv_timedwait_sig 171except that they take 172.Vt struct mtx 173argument 174.Fa m . 175.Sh IMPLEMENTATION NOTES 176Condition variables exist primarily for code imported from other systems; for 177.Dx 178code, the 179.Fn tsleep 180/ 181.Fn wakeup 182family of functions should be used instead. 183.Sh RETURN VALUES 184If successful, 185.Fn cv_wait_sig , 186.Fn cv_timedwait , 187.Fn cv_timedwait_sig 188.Fn cv_mtx_wait_sig , 189.Fn cv_mtx_timedwait , 190and 191.Fn cv_mtx_timedwait_sig 192return 0. 193Otherwise, a non-zero error code is returned. 194.Sh FILES 195Condition variables are implemented in 196.Pa /sys/kern/kern_condvar.c . 197The public interface and structure is found in 198.Pa /sys/sys/condvar.h . 199.Sh SEE ALSO 200.Xr locking 9 , 201.Xr lockmgr 9 , 202.Xr mutex 9 , 203.Xr tsleep 9 204.Sh HISTORY 205Condition variables appeared in 206.Dx 2.7 . 207.Sh AUTHORS 208This manual page was written by 209.An Jason Evans 210for 211.Fx . 212