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 April 16, 2010
  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 .Pp
 101 A thread must hold
 102 .Fa l
 103 before calling
 104 .Fn cv_wait ,
 105 .Fn cv_wait_sig ,
 106 .Fn cv_timedwait ,
 107 or
 108 .Fn cv_timedwait_sig .
 109 When a thread waits on a condition,
 110 .Fa l
 111 is atomically released before the thread is blocked, then atomically reacquired
 112 before the function call returns.
 113 All waiters must pass the same
 114 .Fa l
 115 in conjunction with
 116 .Fa cvp .
 117 .Pp
 118 When
 119 .Fn cv_wait ,
 120 .Fn cv_wait_sig ,
 121 .Fn cv_timedwait ,
 122 and
 123 .Fn cv_timedwait_sig
 124 unblock, their calling threads are made runnable.
 125 .Fn cv_timedwait
 126 and
 127 .Fn cv_timedwait_sig
 128 wait for at most
 129 .Fa timo
 130 seconds before being unblocked and returning
 131 .Er EWOULDBLOCK ;
 132 otherwise, they return 0.
 133 .Fn cv_wait_sig
 134 and
 135 .Fn cv_timedwait_sig
 136 return prematurely with a value of
 137 .Er EINTR
 138 or
 139 .Er ERESTART
 140 if a signal is caught, or 0 if signaled via
 141 .Fn cv_signal
 142 or
 143 .Fn cv_broadcast .
 144 .Sh IMPLEMENTATION NOTES
 145 Condition variables exist primarily for code imported from other systems; for
 146 .Dx
 147 code, the
 148 .Fn tsleep /
 149 .Fn wakeup
 150 family of functions should be used instead.
 151 .Pp
 152 Condition variables can currently only release
 153 .Xr lockmgr 9
 154 locks.
 155 .Sh RETURN VALUES
 156 If successful,
 157 .Fn cv_wait_sig ,
 158 .Fn cv_timedwait ,
 159 and
 160 .Fn cv_timedwait_sig
 161 return 0.
 162 Otherwise, a non-zero error code is returned.
 163 .Sh FILES
 164 Condition variables are implemented in
 165 .Pa /sys/kern/kern_condvar.c .
 166 The public interface and structure is found in
 167 .Pa /sys/sys/condvar.h .
 168 .Sh SEE ALSO
 169 .Xr lockmgr 9 ,
 170 .Xr tsleep 9
 171 .Sh HISTORY
 172 Condition variables appeared in
 173 .Dx 2.7 .
 174 .Sh AUTHORS
 175 This manual page was written by
 176 .An Jason Evans
 177 for
 178 .Fx .