share/man/man9/condvar.9

   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
  80 Condition variables are used in conjunction with locks to wait for conditions
  81 to occur.
  82 Condition variables are created with
  83 .Fn cv_init ,
  84 where
  85 .Fa cvp
  86 is a pointer to space for a
  87 .Vt struct cv ,
  88 and
  89 .Fa desc
  90 is a pointer to a null-terminated character string that describes the condition
  91 variable.
  92 Condition variables are destroyed with
  93 .Fn cv_destroy .
  94 Threads wait on condition variables by calling
  95 .Fn cv_wait ,
  96 .Fn cv_wait_sig ,
  97 .Fn cv_timedwait ,
  98 or
  99 .Fn cv_timedwait_sig .
 100 Threads unblock waiters by calling
 101 .Fn cv_signal
 102 to unblock one waiter, or
 103 .Fn cv_broadcast
 104 or
 105 .Fn cv_broadcastpri
 106 to unblock all waiters.
 107 .Fn cv_broadcastpri
 108 is a synonym for
 109 .Fn cv_broadcast
 110 in
 111 .Dx
 112 and discards the
 113 .Fa pri
 114 parameter.
 115 .Pp
 116 A thread must hold
 117 .Fa l
 118 before calling
 119 .Fn cv_wait ,
 120 .Fn cv_wait_sig ,
 121 .Fn cv_timedwait ,
 122 or
 123 .Fn cv_timedwait_sig .
 124 When a thread waits on a condition,
 125 .Fa l
 126 is atomically released before the thread is blocked, then atomically reacquired
 127 before the function call returns.
 128 All waiters must pass the same
 129 .Fa l
 130 in conjunction with
 131 .Fa cvp .
 132 .Pp
 133 When
 134 .Fn cv_wait ,
 135 .Fn cv_wait_sig ,
 136 .Fn cv_timedwait ,
 137 and
 138 .Fn cv_timedwait_sig
 139 unblock, their calling threads are made runnable.
 140 .Fn cv_timedwait
 141 and
 142 .Fn cv_timedwait_sig
 143 wait for at most
 144 .Fa timo
 145 / hz seconds before being unblocked and returning
 146 .Er EWOULDBLOCK ;
 147 otherwise, they return 0.
 148 .Fn cv_wait_sig
 149 and
 150 .Fn cv_timedwait_sig
 151 return prematurely with a value of
 152 .Er EINTR
 153 or
 154 .Er ERESTART
 155 if a signal is caught, or 0 if signaled via
 156 .Fn cv_signal
 157 or
 158 .Fn cv_broadcast .
 159 .Pp
 160 .Fn cv_mtx_wait ,
 161 .Fn cv_mtx_wait_sig ,
 162 .Fn cv_mtx_timedwait ,
 163 and
 164 .Fn cv_mtx_timedwait_sig
 165 work the same as
 166 .Fn cv_wait ,
 167 .Fn cv_wait_sig ,
 168 .Fn cv_timedwait ,
 169 and
 170 .Fn cv_timedwait_sig
 171 except that they take
 172 .Vt struct mtx
 173 argument
 174 .Fa m .
 175 .Sh IMPLEMENTATION NOTES
 176 Condition variables exist primarily for code imported from other systems; for
 177 .Dx
 178 code, the
 179 .Fn tsleep
 180 /
 181 .Fn wakeup
 182 family of functions should be used instead.
 183 .Sh RETURN VALUES
 184 If 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 ,
 190 and
 191 .Fn cv_mtx_timedwait_sig
 192 return 0.
 193 Otherwise, a non-zero error code is returned.
 194 .Sh FILES
 195 Condition variables are implemented in
 196 .Pa /sys/kern/kern_condvar.c .
 197 The 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
 205 Condition variables appeared in
 206 .Dx 2.7 .
 207 .Sh AUTHORS
 208 This manual page was written by
 209 .An Jason Evans
 210 for
 211 .Fx .