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