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 1, 2006
  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_timedwait ,
  39 .Nm cv_timedwait_sig ,
  40 .Nm cv_signal ,
  41 .Nm cv_broadcast ,
  42 .Nm cv_broadcastpri ,
  43 .Nm cv_wmesg
  44 .Nd kernel condition variable
  45 .Sh SYNOPSIS
  46 .In sys/param.h
  47 .In sys/proc.h
  48 .In sys/condvar.h
  49 .Ft void
  50 .Fn cv_init "struct cv *cvp" "const char *desc"
  51 .Ft void
  52 .Fn cv_destroy "struct cv *cvp"
  53 .Ft void
  54 .Fn cv_wait "struct cv *cvp" "struct mtx *mp"
  55 .Ft int
  56 .Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp"
  57 .Ft int
  58 .Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo"
  59 .Ft int
  60 .Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "int timo"
  61 .Ft void
  62 .Fn cv_signal "struct cv *cvp"
  63 .Ft void
  64 .Fn cv_broadcast "struct cv *cvp"
  65 .Ft void
  66 .Fn cv_broadcastpri "struct cv *cvp" "int pri"
  67 .Ft const char *
  68 .Fn cv_wmesg "struct cv *cvp"
  69 .Sh DESCRIPTION
  70 Condition variables are used in conjunction with mutexes to wait for conditions
  71 to occur.
  72 Condition variables are created with
  73 .Fn cv_init ,
  74 where
  75 .Fa cvp
  76 is a pointer to space for a
  77 .Vt struct cv ,
  78 and
  79 .Fa desc
  80 is a pointer to a null-terminated character string that describes the condition
  81 variable.
  82 Condition variables are destroyed with
  83 .Fn cv_destroy .
  84 Threads wait on condition variables by calling
  85 .Fn cv_wait ,
  86 .Fn cv_wait_sig ,
  87 .Fn cv_timedwait ,
  88 or
  89 .Fn cv_timedwait_sig .
  90 Threads unblock waiters by calling
  91 .Fn cv_signal
  92 to unblock one waiter, or
  93 .Fn cv_broadcast
  94 or
  95 .Fn cv_broadcastpri
  96 to unblock all waiters.
  97 In addition to waking waiters,
  98 .Fn cv_broadcastpri
  99 ensures that all of the waiters have a priority of at least
 100 .Fa pri
 101 by raising the priority of any threads that do not.
 102 .Fn cv_wmesg
 103 returns the description string of
 104 .Fa cvp ,
 105 as set by the initial call to
 106 .Fn cv_init .
 107 .Pp
 108 A thread must hold
 109 .Fa mp
 110 before calling
 111 .Fn cv_wait ,
 112 .Fn cv_wait_sig ,
 113 .Fn cv_timedwait ,
 114 or
 115 .Fn cv_timedwait_sig .
 116 When a thread waits on a condition,
 117 .Fa mp
 118 is atomically released before the thread is blocked, then atomically reacquired
 119 before the function call returns.
 120 All waiters must pass the same
 121 .Fa mp
 122 in conjunction with
 123 .Fa cvp .
 124 .Pp
 125 When
 126 .Fn cv_wait ,
 127 .Fn cv_wait_sig ,
 128 .Fn cv_timedwait ,
 129 and
 130 .Fn cv_timedwait_sig
 131 unblock, their calling threads are made runnable.
 132 .Fn cv_timedwait
 133 and
 134 .Fn cv_timedwait_sig
 135 wait for at most
 136 .Fa timo
 137 /
 138 .Dv HZ
 139 seconds before being unblocked and returning
 140 .Er EWOULDBLOCK ;
 141 otherwise, they return 0.
 142 .Fn cv_wait_sig
 143 and
 144 .Fn cv_timedwait_sig
 145 return prematurely with a value of
 146 .Er EINTR
 147 or
 148 .Er ERESTART
 149 if a signal is caught, or 0 if signaled via
 150 .Fn cv_signal
 151 or
 152 .Fn cv_broadcast .
 153 .Sh RETURN VALUES
 154 If successful,
 155 .Fn cv_wait_sig ,
 156 .Fn cv_timedwait ,
 157 and
 158 .Fn cv_timedwait_sig
 159 return 0.
 160 Otherwise, a non-zero error code is returned.
 161 .Pp
 162 .Fn cv_wmesg
 163 returns the description string that was passed to
 164 .Fn cv_init .
 165 .Sh ERRORS
 166 .Fn cv_wait_sig
 167 and
 168 .Fn cv_timedwait_sig
 169 will fail if:
 170 .Bl -tag -width Er
 171 .It Bq Er EINTR
 172 An unmasked signal was caught.
 173 .It Bq Er ERESTART
 174 A masked signal was caught.
 175 .El
 176 .Pp
 177 .Fn cv_timedwait
 178 and
 179 .Fn cv_timedwait_sig
 180 will fail if:
 181 .Bl -tag -width Er
 182 .It Bq Er EWOULDBLOCK
 183 Timeout expired.
 184 .El
 185 .Sh SEE ALSO
 186 .Xr msleep 9 ,
 187 .Xr mtx_pool 9 ,
 188 .Xr mutex 9 ,
 189 .Xr rwlock 9 ,
 190 .Xr sema 9 ,
 191 .Xr sx 9