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 March 21, 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 thread must hold
 121 .Fa lock
 122 before calling
 123 .Fn cv_wait ,
 124 .Fn cv_wait_sig ,
 125 .Fn cv_wait_unlock ,
 126 .Fn cv_timedwait ,
 127 or
 128 .Fn cv_timedwait_sig .
 129 When a thread waits on a condition,
 130 .Fa lock
 131 is atomically released before the thread is blocked, then reacquired
 132 before the function call returns.
 133 The
 134 .Fn cv_wait_unlock
 135 function does not reacquire the lock before returning.
 136 All waiters must pass the same
 137 .Fa lock
 138 in conjunction with
 139 .Fa cvp .
 140 .Pp
 141 When
 142 .Fn cv_wait ,
 143 .Fn cv_wait_sig ,
 144 .Fn cv_wait_unlock ,
 145 .Fn cv_timedwait ,
 146 and
 147 .Fn cv_timedwait_sig
 148 unblock, their calling threads are made runnable.
 149 .Fn cv_timedwait
 150 and
 151 .Fn cv_timedwait_sig
 152 wait for at most
 153 .Fa timo
 154 /
 155 .Dv HZ
 156 seconds before being unblocked and returning
 157 .Er EWOULDBLOCK ;
 158 otherwise, they return 0.
 159 .Fn cv_wait_sig
 160 and
 161 .Fn cv_timedwait_sig
 162 return prematurely with a value of
 163 .Er EINTR
 164 or
 165 .Er ERESTART
 166 if a signal is caught, or 0 if signaled via
 167 .Fn cv_signal
 168 or
 169 .Fn cv_broadcast .
 170 .Sh RETURN VALUES
 171 If successful,
 172 .Fn cv_wait_sig ,
 173 .Fn cv_timedwait ,
 174 and
 175 .Fn cv_timedwait_sig
 176 return 0.
 177 Otherwise, a non-zero error code is returned.
 178 .Pp
 179 .Fn cv_wmesg
 180 returns the description string that was passed to
 181 .Fn cv_init .
 182 .Sh ERRORS
 183 .Fn cv_wait_sig
 184 and
 185 .Fn cv_timedwait_sig
 186 will fail if:
 187 .Bl -tag -width Er
 188 .It Bq Er EINTR
 189 A signal was caught and the system call should be interrupted.
 190 .It Bq Er ERESTART
 191 A signal was caught and the system call should be restarted.
 192 .El
 193 .Pp
 194 .Fn cv_timedwait
 195 and
 196 .Fn cv_timedwait_sig
 197 will fail if:
 198 .Bl -tag -width Er
 199 .It Bq Er EWOULDBLOCK
 200 Timeout expired.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr mtx_pool 9 ,
 204 .Xr mutex 9 ,
 205 .Xr rwlock 9 ,
 206 .Xr sema 9 ,
 207 .Xr sleep 9 ,
 208 .Xr sx 9