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 August 11, 2011
  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_signal ,
  42 .Nm cv_broadcast ,
  43 .Nm cv_broadcastpri
  44 .Nd kernel condition variable
  45 .Sh SYNOPSIS
  46 .In sys/param.h
  47 .In sys/systm.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 lock *l"
  55 .Ft int
  56 .Fn cv_wait_sig "struct cv *cvp" "struct lock *l"
  57 .Ft int
  58 .Fn cv_timedwait "struct cv *cvp" "struct lock *l" "int timo"
  59 .Ft int
  60 .Fn cv_timedwait_sig "struct cv *cvp" "struct lock *l" "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 .Sh DESCRIPTION
  68 Condition variables are used in conjunction with locks to wait for conditions
  69 to occur.
  70 Condition variables are created with
  71 .Fn cv_init ,
  72 where
  73 .Fa cvp
  74 is a pointer to space for a
  75 .Vt struct cv ,
  76 and
  77 .Fa desc
  78 is a pointer to a null-terminated character string that describes the condition
  79 variable.
  80 Condition variables are destroyed with
  81 .Fn cv_destroy .
  82 Threads wait on condition variables by calling
  83 .Fn cv_wait ,
  84 .Fn cv_wait_sig ,
  85 .Fn cv_timedwait ,
  86 or
  87 .Fn cv_timedwait_sig .
  88 Threads unblock waiters by calling
  89 .Fn cv_signal
  90 to unblock one waiter, or
  91 .Fn cv_broadcast
  92 or
  93 .Fn cv_broadcastpri
  94 to unblock all waiters.
  95 .Fn cv_broadcastpri
  96 is a synonym for
  97 .Fn cv_broadcast
  98 in
  99 .Dx
 100 and discards the
 101 .Fa pri
 102 parameter.
 103 .Pp
 104 A thread must hold
 105 .Fa l
 106 before calling
 107 .Fn cv_wait ,
 108 .Fn cv_wait_sig ,
 109 .Fn cv_timedwait ,
 110 or
 111 .Fn cv_timedwait_sig .
 112 When a thread waits on a condition,
 113 .Fa l
 114 is atomically released before the thread is blocked, then atomically reacquired
 115 before the function call returns.
 116 All waiters must pass the same
 117 .Fa l
 118 in conjunction with
 119 .Fa cvp .
 120 .Pp
 121 When
 122 .Fn cv_wait ,
 123 .Fn cv_wait_sig ,
 124 .Fn cv_timedwait ,
 125 and
 126 .Fn cv_timedwait_sig
 127 unblock, their calling threads are made runnable.
 128 .Fn cv_timedwait
 129 and
 130 .Fn cv_timedwait_sig
 131 wait for at most
 132 .Fa timo
 133 seconds before being unblocked and returning
 134 .Er EWOULDBLOCK ;
 135 otherwise, they return 0.
 136 .Fn cv_wait_sig
 137 and
 138 .Fn cv_timedwait_sig
 139 return prematurely with a value of
 140 .Er EINTR
 141 or
 142 .Er ERESTART
 143 if a signal is caught, or 0 if signaled via
 144 .Fn cv_signal
 145 or
 146 .Fn cv_broadcast .
 147 .Sh IMPLEMENTATION NOTES
 148 Condition variables exist primarily for code imported from other systems; for
 149 .Dx
 150 code, the
 151 .Fn tsleep /
 152 .Fn wakeup
 153 family of functions should be used instead.
 154 .Pp
 155 Condition variables can currently only release
 156 .Xr lockmgr 9
 157 locks.
 158 .Sh RETURN VALUES
 159 If successful,
 160 .Fn cv_wait_sig ,
 161 .Fn cv_timedwait ,
 162 and
 163 .Fn cv_timedwait_sig
 164 return 0.
 165 Otherwise, a non-zero error code is returned.
 166 .Sh FILES
 167 Condition variables are implemented in
 168 .Pa /sys/kern/kern_condvar.c .
 169 The public interface and structure is found in
 170 .Pa /sys/sys/condvar.h .
 171 .Sh SEE ALSO
 172 .Xr lockmgr 9 ,
 173 .Xr tsleep 9
 174 .Sh HISTORY
 175 Condition variables appeared in
 176 .Dx 2.7 .
 177 .Sh AUTHORS
 178 This manual page was written by
 179 .An Jason Evans
 180 for
 181 .Fx .