share/man/man9/condvar.9

   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 19, 2013
  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_sbt ,
  41 .Nm cv_timedwait_sig ,
  42 .Nm cv_timedwait_sig_sbt ,
  43 .Nm cv_signal ,
  44 .Nm cv_broadcast ,
  45 .Nm cv_broadcastpri ,
  46 .Nm cv_wmesg
  47 .Nd kernel condition variable
  48 .Sh SYNOPSIS
  49 .In sys/param.h
  50 .In sys/proc.h
  51 .In sys/condvar.h
  52 .Ft void
  53 .Fn cv_init "struct cv *cvp" "const char *desc"
  54 .Ft void
  55 .Fn cv_destroy "struct cv *cvp"
  56 .Ft void
  57 .Fn cv_wait "struct cv *cvp" "lock"
  58 .Ft int
  59 .Fn cv_wait_sig "struct cv *cvp" "lock"
  60 .Ft void
  61 .Fn cv_wait_unlock "struct cv *cvp" "lock"
  62 .Ft int
  63 .Fn cv_timedwait "struct cv *cvp" "lock" "int timo"
  64 .Ft int
  65 .Fn cv_timedwait_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
  66 "sbintime_t pr" "int flags"
  67 .Ft int
  68 .Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo"
  69 .Ft int
  70 .Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
  71 "sbintime_t pr" "int flags"
  72 .Ft void
  73 .Fn cv_signal "struct cv *cvp"
  74 .Ft void
  75 .Fn cv_broadcast "struct cv *cvp"
  76 .Ft void
  77 .Fn cv_broadcastpri "struct cv *cvp" "int pri"
  78 .Ft const char *
  79 .Fn cv_wmesg "struct cv *cvp"
  80 .Sh DESCRIPTION
  81 Condition variables are used in conjunction with mutexes to wait for conditions
  82 to occur.
  83 Condition variables are created with
  84 .Fn cv_init ,
  85 where
  86 .Fa cvp
  87 is a pointer to space for a
  88 .Vt struct cv ,
  89 and
  90 .Fa desc
  91 is a pointer to a null-terminated character string that describes the condition
  92 variable.
  93 Condition variables are destroyed with
  94 .Fn cv_destroy .
  95 Threads wait on condition variables by calling
  96 .Fn cv_wait ,
  97 .Fn cv_wait_sig ,
  98 .Fn cv_wait_unlock ,
  99 .Fn cv_timedwait ,
 100 or
 101 .Fn cv_timedwait_sig .
 102 Threads unblock waiters by calling
 103 .Fn cv_signal
 104 to unblock one waiter, or
 105 .Fn cv_broadcast
 106 or
 107 .Fn cv_broadcastpri
 108 to unblock all waiters.
 109 In addition to waking waiters,
 110 .Fn cv_broadcastpri
 111 ensures that all of the waiters have a priority of at least
 112 .Fa pri
 113 by raising the priority of any threads that do not.
 114 .Fn cv_wmesg
 115 returns the description string of
 116 .Fa cvp ,
 117 as set by the initial call to
 118 .Fn cv_init .
 119 .Pp
 120 The
 121 .Fa lock
 122 argument is a pointer to either a
 123 .Xr mutex 9 ,
 124 .Xr rwlock 9 ,
 125 or
 126 .Xr sx 9
 127 lock.
 128 A
 129 .Xr mutex 9
 130 argument must be initialized with
 131 .Dv MTX_DEF
 132 and not
 133 .Dv MTX_SPIN .
 134 A thread must hold
 135 .Fa lock
 136 before calling
 137 .Fn cv_wait ,
 138 .Fn cv_wait_sig ,
 139 .Fn cv_wait_unlock ,
 140 .Fn cv_timedwait ,
 141 or
 142 .Fn cv_timedwait_sig .
 143 When a thread waits on a condition,
 144 .Fa lock
 145 is atomically released before the thread is blocked, then reacquired
 146 before the function call returns.
 147 In addition, the thread will fully drop the
 148 .Va Giant
 149 mutex
 150 (even if recursed)
 151 while the it is suspended and will reacquire the
 152 .Va Giant
 153 mutex before the function returns.
 154 The
 155 .Fn cv_wait_unlock
 156 function does not reacquire the lock before returning.
 157 Note that the
 158 .Va Giant
 159 mutex may be specified as
 160 .Fa lock .
 161 However,
 162 .Va Giant
 163 may not be used as
 164 .Fa lock
 165 for the
 166 .Fn cv_wait_unlock
 167 function.
 168 All waiters must pass the same
 169 .Fa lock
 170 in conjunction with
 171 .Fa cvp .
 172 .Pp
 173 When
 174 .Fn cv_wait ,
 175 .Fn cv_wait_sig ,
 176 .Fn cv_wait_unlock ,
 177 .Fn cv_timedwait ,
 178 and
 179 .Fn cv_timedwait_sig
 180 unblock, their calling threads are made runnable.
 181 .Fn cv_timedwait
 182 and
 183 .Fn cv_timedwait_sig
 184 wait for at most
 185 .Fa timo
 186 /
 187 .Dv HZ
 188 seconds before being unblocked and returning
 189 .Er EWOULDBLOCK ;
 190 otherwise, they return 0.
 191 .Fn cv_wait_sig
 192 and
 193 .Fn cv_timedwait_sig
 194 return prematurely with a value of
 195 .Er EINTR
 196 or
 197 .Er ERESTART
 198 if a signal is caught, or 0 if signaled via
 199 .Fn cv_signal
 200 or
 201 .Fn cv_broadcast .
 202 .Pp
 203 .Fn cv_timedwait_sbt
 204 and
 205 .Fn cv_timedwait_sig_sbt
 206 functions take
 207 .Fa sbt
 208 argument instead of
 209 .Fa timo .
 210 It allows to specify relative or absolute unblock time with higher resolution
 211 in form of
 212 .Vt sbintime_t .
 213 The parameter
 214 .Fa pr
 215 allows to specify wanted absolute event precision.
 216 The parameter
 217 .Fa flags
 218 allows to pass additional
 219 .Fn callout_reset_sbt
 220 flags.
 221 .Sh RETURN VALUES
 222 If successful,
 223 .Fn cv_wait_sig ,
 224 .Fn cv_timedwait ,
 225 and
 226 .Fn cv_timedwait_sig
 227 return 0.
 228 Otherwise, a non-zero error code is returned.
 229 .Pp
 230 .Fn cv_wmesg
 231 returns the description string that was passed to
 232 .Fn cv_init .
 233 .Sh ERRORS
 234 .Fn cv_wait_sig
 235 and
 236 .Fn cv_timedwait_sig
 237 will fail if:
 238 .Bl -tag -width Er
 239 .It Bq Er EINTR
 240 A signal was caught and the system call should be interrupted.
 241 .It Bq Er ERESTART
 242 A signal was caught and the system call should be restarted.
 243 .El
 244 .Pp
 245 .Fn cv_timedwait
 246 and
 247 .Fn cv_timedwait_sig
 248 will fail if:
 249 .Bl -tag -width Er
 250 .It Bq Er EWOULDBLOCK
 251 Timeout expired.
 252 .El
 253 .Sh SEE ALSO
 254 .Xr locking 9 ,
 255 .Xr mtx_pool 9 ,
 256 .Xr mutex 9 ,
 257 .Xr rwlock 9 ,
 258 .Xr sema 9 ,
 259 .Xr sleep 9 ,
 260 .Xr sx 9 ,
 261 .Xr timeout 9