share/man/man9/sx.9

   1 .\"
   2 .\" Copyright (C) 2001 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 SX 9
  31 .Os
  32 .Sh NAME
  33 .Nm sx ,
  34 .Nm sx_init ,
  35 .Nm sx_destroy ,
  36 .Nm sx_slock ,
  37 .Nm sx_xlock ,
  38 .Nm sx_try_slock ,
  39 .Nm sx_try_xlock ,
  40 .Nm sx_sunlock ,
  41 .Nm sx_xunlock ,
  42 .Nm sx_unlock ,
  43 .Nm sx_try_upgrade ,
  44 .Nm sx_downgrade ,
  45 .Nm sx_sleep ,
  46 .Nm sx_xlocked ,
  47 .Nm sx_assert ,
  48 .Nm SX_SYSINIT
  49 .Nd kernel shared/exclusive lock
  50 .Sh SYNOPSIS
  51 .In sys/param.h
  52 .In sys/lock.h
  53 .In sys/sx.h
  54 .Ft void
  55 .Fn sx_init "struct sx *sx" "const char *description"
  56 .Ft void
  57 .Fn sx_destroy "struct sx *sx"
  58 .Ft void
  59 .Fn sx_slock "struct sx *sx"
  60 .Ft void
  61 .Fn sx_xlock "struct sx *sx"
  62 .Ft int
  63 .Fn sx_try_slock "struct sx *sx"
  64 .Ft int
  65 .Fn sx_try_xlock "struct sx *sx"
  66 .Ft void
  67 .Fn sx_sunlock "struct sx *sx"
  68 .Ft void
  69 .Fn sx_xunlock "struct sx *sx"
  70 .Ft void
  71 .Fn sx_unlock "struct sx *sx"
  72 .Ft int
  73 .Fn sx_try_upgrade "struct sx *sx"
  74 .Ft void
  75 .Fn sx_downgrade "struct sx *sx"
  76 .Ft int
  77 .Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
  78 .Ft int
  79 .Fn sx_xlocked "struct sx *sx"
  80 .Pp
  81 .Cd "options INVARIANTS"
  82 .Cd "options INVARIANT_SUPPORT"
  83 .Ft void
  84 .Fn sx_assert "struct sx *sx" "int what"
  85 .In sys/kernel.h
  86 .Fn SX_SYSINIT "name" "struct sx *sx" "const char *description"
  87 .Sh DESCRIPTION
  88 Shared/exclusive locks are used to protect data that are read far more often
  89 than they are written.
  90 Mutexes are inherently more efficient than shared/exclusive locks, so
  91 shared/exclusive locks should be used prudently.
  92 .Pp
  93 Shared/exclusive locks are created with
  94 .Fn sx_init ,
  95 where
  96 .Fa sx
  97 is a pointer to space for a
  98 .Vt struct sx ,
  99 and
 100 .Fa description
 101 is a pointer to a null-terminated character string that describes the
 102 shared/exclusive lock.
 103 Shared/exclusive locks are destroyed with
 104 .Fn sx_destroy .
 105 Threads acquire and release a shared lock by calling
 106 .Fn sx_slock
 107 or
 108 .Fn sx_try_slock
 109 and
 110 .Fn sx_sunlock
 111 or
 112 .Fn sx_unlock .
 113 Threads acquire and release an exclusive lock by calling
 114 .Fn sx_xlock
 115 or
 116 .Fn sx_try_xlock
 117 and
 118 .Fn sx_xunlock
 119 or
 120 .Fn sx_unlock .
 121 A thread can attempt to upgrade a currently held shared lock to an exclusive
 122 lock by calling
 123 .Fn sx_try_upgrade .
 124 A thread that has an exclusive lock can downgrade it to a shared lock by
 125 calling
 126 .Fn sx_downgrade .
 127 .Pp
 128 .Fn sx_try_slock
 129 and
 130 .Fn sx_try_xlock
 131 will return 0 if the shared/exclusive lock cannot be acquired immediately;
 132 otherwise the shared/exclusive lock will be acquired and a non-zero value will
 133 be returned.
 134 .Pp
 135 .Fn sx_try_upgrade
 136 will return 0 if the shared lock cannot be upgraded to an exclusive lock
 137 immediately; otherwise the exclusive lock will be acquired and a non-zero value
 138 will be returned.
 139 .Pp
 140 A thread can atomically release a shared/exclusive lock while waiting for an
 141 event by calling
 142 .Fn sx_sleep .
 143 For more details on the parameters to this function,
 144 see
 145 .Xr sleep 9 .
 146 .Pp
 147 When compiled with
 148 .Cd "options INVARIANTS"
 149 and
 150 .Cd "options INVARIANT_SUPPORT" ,
 151 the
 152 .Fn sx_assert
 153 function tests
 154 .Fa sx
 155 for the assertions specified in
 156 .Fa what ,
 157 and panics if they are not met.
 158 The following assertions are supported:
 159 .Bl -tag -width ".Dv SX_UNLOCKED"
 160 .It Dv SX_LOCKED
 161 Assert that the current thread has either a shared or an exclusive lock on the
 162 .Vt sx
 163 lock pointed to by the first argument.
 164 .It Dv SX_SLOCKED
 165 Assert that the current thread has a shared lock on the
 166 .Vt sx
 167 lock pointed to by
 168 the first argument.
 169 .It Dv SX_XLOCKED
 170 Assert that the current thread has an exclusive lock on the
 171 .Vt sx
 172 lock pointed to
 173 by the first argument.
 174 .It Dv SX_UNLOCKED
 175 Assert that the current thread has no lock on the
 176 .Vt sx
 177 lock pointed to
 178 by the first argument.
 179 .El
 180 .Pp
 181 .Fn sx_xlocked
 182 will return non-zero if the current thread holds the exclusive lock;
 183 otherwise, it will return zero.
 184 .Pp
 185 For ease of programming,
 186 .Fn sx_unlock
 187 is provided as a macro frontend to the respective functions,
 188 .Fn sx_sunlock
 189 and
 190 .Fn sx_xunlock .
 191 Algorithms that are aware of what state the lock is in should use either
 192 of the two specific functions for a minor performance benefit.
 193 .Pp
 194 The
 195 .Fn SX_SYSINIT
 196 macro is used to generate a call to the
 197 .Fn sx_sysinit
 198 routine at system startup in order to initialize a given
 199 .Fa sx
 200 lock.
 201 The parameters are the same as
 202 .Fn sx_init
 203 but with an additional argument,
 204 .Fa name ,
 205 that is used in generating unique variable names for the related
 206 structures associated with the lock and the sysinit routine.
 207 .Pp
 208 A thread may not hold both a shared lock and an exclusive lock on the same
 209 lock simultaneously;
 210 attempting to do so will result in deadlock.
 211 .Sh CONTEXT
 212 A thread may hold a shared or exclusive lock on an
 213 .Nm
 214 lock while sleeping.
 215 As a result, an
 216 .Nm
 217 lock may not be acquired while holding a mutex.
 218 Otherwise, if one thread slept while holding an
 219 .Nm
 220 lock while another thread blocked on the same
 221 .Nm
 222 lock after acquiring a mutex, then the second thread would effectively
 223 end up sleeping while holding a mutex, which is not allowed.
 224 .Sh SEE ALSO
 225 .Xr mutex 9 ,
 226 .Xr panic 9 ,
 227 .Xr rwlock 9 ,
 228 .Xr sema 9
 229 .Sh BUGS
 230 Currently there is no way to assert that a lock is not held.
 231 This is not possible in the
 232 .No non- Ns Dv WITNESS
 233 case for asserting that this thread
 234 does not hold a shared lock.
 235 In the
 236 .No non- Ns Dv WITNESS
 237 case, the
 238 .Dv SX_LOCKED
 239 and
 240 .Dv SX_SLOCKED
 241 assertions merely check that some thread holds a shared lock.
 242 They do not ensure that the current thread holds a shared lock.