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 March 13, 2016
  30 .Dt SX 9
  31 .Os
  32 .Sh NAME
  33 .Nm sx ,
  34 .Nm sx_init ,
  35 .Nm sx_init_flags ,
  36 .Nm sx_destroy ,
  37 .Nm sx_slock ,
  38 .Nm sx_xlock ,
  39 .Nm sx_slock_sig ,
  40 .Nm sx_xlock_sig ,
  41 .Nm sx_try_slock ,
  42 .Nm sx_try_xlock ,
  43 .Nm sx_sunlock ,
  44 .Nm sx_xunlock ,
  45 .Nm sx_unlock ,
  46 .Nm sx_try_upgrade ,
  47 .Nm sx_downgrade ,
  48 .Nm sx_sleep ,
  49 .Nm sx_xholder ,
  50 .Nm sx_xlocked ,
  51 .Nm sx_assert ,
  52 .Nm SX_SYSINIT
  53 .Nd kernel shared/exclusive lock
  54 .Sh SYNOPSIS
  55 .In sys/param.h
  56 .In sys/lock.h
  57 .In sys/sx.h
  58 .Ft void
  59 .Fn sx_init "struct sx *sx" "const char *description"
  60 .Ft void
  61 .Fn sx_init_flags "struct sx *sx" "const char *description" "int opts"
  62 .Ft void
  63 .Fn sx_destroy "struct sx *sx"
  64 .Ft void
  65 .Fn sx_slock "struct sx *sx"
  66 .Ft void
  67 .Fn sx_xlock "struct sx *sx"
  68 .Ft int
  69 .Fn sx_slock_sig "struct sx *sx"
  70 .Ft int
  71 .Fn sx_xlock_sig "struct sx *sx"
  72 .Ft int
  73 .Fn sx_try_slock "struct sx *sx"
  74 .Ft int
  75 .Fn sx_try_xlock "struct sx *sx"
  76 .Ft void
  77 .Fn sx_sunlock "struct sx *sx"
  78 .Ft void
  79 .Fn sx_xunlock "struct sx *sx"
  80 .Ft void
  81 .Fn sx_unlock "struct sx *sx"
  82 .Ft int
  83 .Fn sx_try_upgrade "struct sx *sx"
  84 .Ft void
  85 .Fn sx_downgrade "struct sx *sx"
  86 .Ft int
  87 .Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo"
  88 .Ft "struct thread *"
  89 .Fn sx_xholder "struct sx *sx"
  90 .Ft int
  91 .Fn sx_xlocked "const struct sx *sx"
  92 .Pp
  93 .Cd "options INVARIANTS"
  94 .Cd "options INVARIANT_SUPPORT"
  95 .Ft void
  96 .Fn sx_assert "const struct sx *sx" "int what"
  97 .In sys/kernel.h
  98 .Fn SX_SYSINIT "name" "struct sx *sx" "const char *description"
  99 .Sh DESCRIPTION
 100 Shared/exclusive locks are used to protect data that are read far more often
 101 than they are written.
 102 Shared/exclusive locks do not implement priority propagation like mutexes and
 103 reader/writer locks to prevent priority inversions, so
 104 shared/exclusive locks should be used prudently.
 105 .Pp
 106 Shared/exclusive locks are created with either
 107 .Fn sx_init
 108 or
 109 .Fn sx_init_flags
 110 where
 111 .Fa sx
 112 is a pointer to space for a
 113 .Vt struct sx ,
 114 and
 115 .Fa description
 116 is a pointer to a null-terminated character string that describes the
 117 shared/exclusive lock.
 118 The
 119 .Fa opts
 120 argument to
 121 .Fn sx_init_flags
 122 specifies a set of optional flags to alter the behavior of
 123 .Fa sx .
 124 It contains one or more of the following flags:
 125 .Bl -tag -width SX_NOADAPTIVE
 126 .It Dv SX_NOADAPTIVE
 127 Disable adaptive spinning, rather than sleeping, for lock operations
 128 while an exclusive lock holder is executing on another CPU.
 129 Adaptive spinning is the default unless the kernel is compiled with
 130 .Cd "options NO_ADAPTIVE_SX" .
 131 .It Dv SX_DUPOK
 132 Witness should not log messages about duplicate locks being acquired.
 133 .It Dv SX_NOWITNESS
 134 Instruct
 135 .Xr witness 4
 136 to ignore this lock.
 137 .It Dv SX_NOPROFILE
 138 Do not profile this lock.
 139 .It Dv SX_RECURSE
 140 Allow threads to recursively acquire exclusive locks for
 141 .Fa sx .
 142 .It Dv SX_QUIET
 143 Do not log any operations for this lock via
 144 .Xr ktr 4 .
 145 .It Dv SX_NEW
 146 If the kernel has been compiled with
 147 .Cd "options INVARIANTS" ,
 148 .Fn sx_init
 149 will assert that the
 150 .Fa sx
 151 has not been initialized multiple times without intervening calls to
 152 .Fn sx_destroy
 153 unless this option is specified.
 154 .El
 155 .Pp
 156 Shared/exclusive locks are destroyed with
 157 .Fn sx_destroy .
 158 The lock
 159 .Fa sx
 160 must not be locked by any thread when it is destroyed.
 161 .Pp
 162 Threads acquire and release a shared lock by calling
 163 .Fn sx_slock ,
 164 .Fn sx_slock_sig
 165 or
 166 .Fn sx_try_slock
 167 and
 168 .Fn sx_sunlock
 169 or
 170 .Fn sx_unlock .
 171 Threads acquire and release an exclusive lock by calling
 172 .Fn sx_xlock ,
 173 .Fn sx_xlock_sig
 174 or
 175 .Fn sx_try_xlock
 176 and
 177 .Fn sx_xunlock
 178 or
 179 .Fn sx_unlock .
 180 A thread can attempt to upgrade a currently held shared lock to an exclusive
 181 lock by calling
 182 .Fn sx_try_upgrade .
 183 A thread that has an exclusive lock can downgrade it to a shared lock by
 184 calling
 185 .Fn sx_downgrade .
 186 .Pp
 187 .Fn sx_try_slock
 188 and
 189 .Fn sx_try_xlock
 190 will return 0 if the shared/exclusive lock cannot be acquired immediately;
 191 otherwise the shared/exclusive lock will be acquired and a non-zero value will
 192 be returned.
 193 .Pp
 194 .Fn sx_try_upgrade
 195 will return 0 if the shared lock cannot be upgraded to an exclusive lock
 196 immediately; otherwise the exclusive lock will be acquired and a non-zero value
 197 will be returned.
 198 .Pp
 199 .Fn sx_slock_sig
 200 and
 201 .Fn sx_xlock_sig
 202 do the same as their normal versions but performing an interruptible sleep.
 203 They return a non-zero value if the sleep has been interrupted by a signal
 204 or an interrupt, otherwise 0.
 205 .Pp
 206 A thread can atomically release a shared/exclusive lock while waiting for an
 207 event by calling
 208 .Fn sx_sleep .
 209 For more details on the parameters to this function,
 210 see
 211 .Xr sleep 9 .
 212 .Pp
 213 When compiled with
 214 .Cd "options INVARIANTS"
 215 and
 216 .Cd "options INVARIANT_SUPPORT" ,
 217 the
 218 .Fn sx_assert
 219 function tests
 220 .Fa sx
 221 for the assertions specified in
 222 .Fa what ,
 223 and panics if they are not met.
 224 One of the following assertions must be specified:
 225 .Bl -tag -width ".Dv SA_UNLOCKED"
 226 .It Dv SA_LOCKED
 227 Assert that the current thread has either a shared or an exclusive lock on the
 228 .Vt sx
 229 lock pointed to by the first argument.
 230 .It Dv SA_SLOCKED
 231 Assert that the current thread has a shared lock on the
 232 .Vt sx
 233 lock pointed to by
 234 the first argument.
 235 .It Dv SA_XLOCKED
 236 Assert that the current thread has an exclusive lock on the
 237 .Vt sx
 238 lock pointed to
 239 by the first argument.
 240 .It Dv SA_UNLOCKED
 241 Assert that the current thread has no lock on the
 242 .Vt sx
 243 lock pointed to
 244 by the first argument.
 245 .El
 246 .Pp
 247 In addition, one of the following optional assertions may be included with
 248 either an
 249 .Dv SA_LOCKED ,
 250 .Dv SA_SLOCKED ,
 251 or
 252 .Dv SA_XLOCKED
 253 assertion:
 254 .Bl -tag -width ".Dv SA_NOTRECURSED"
 255 .It Dv SA_RECURSED
 256 Assert that the current thread has a recursed lock on
 257 .Fa sx .
 258 .It Dv SA_NOTRECURSED
 259 Assert that the current thread does not have a recursed lock on
 260 .Fa sx .
 261 .El
 262 .Pp
 263 .Fn sx_xholder
 264 will return a pointer to the thread which currently holds an exclusive lock on
 265 .Fa sx .
 266 If no thread holds an exclusive lock on
 267 .Fa sx ,
 268 then
 269 .Dv NULL
 270 is returned instead.
 271 .Pp
 272 .Fn sx_xlocked
 273 will return non-zero if the current thread holds the exclusive lock;
 274 otherwise, it will return zero.
 275 .Pp
 276 For ease of programming,
 277 .Fn sx_unlock
 278 is provided as a macro frontend to the respective functions,
 279 .Fn sx_sunlock
 280 and
 281 .Fn sx_xunlock .
 282 Algorithms that are aware of what state the lock is in should use either
 283 of the two specific functions for a minor performance benefit.
 284 .Pp
 285 The
 286 .Fn SX_SYSINIT
 287 macro is used to generate a call to the
 288 .Fn sx_sysinit
 289 routine at system startup in order to initialize a given
 290 .Fa sx
 291 lock.
 292 The parameters are the same as
 293 .Fn sx_init
 294 but with an additional argument,
 295 .Fa name ,
 296 that is used in generating unique variable names for the related
 297 structures associated with the lock and the sysinit routine.
 298 .Pp
 299 A thread may not hold both a shared lock and an exclusive lock on the same
 300 lock simultaneously;
 301 attempting to do so will result in deadlock.
 302 .Sh CONTEXT
 303 A thread may hold a shared or exclusive lock on an
 304 .Nm
 305 lock while sleeping.
 306 As a result, an
 307 .Nm
 308 lock may not be acquired while holding a mutex.
 309 Otherwise, if one thread slept while holding an
 310 .Nm
 311 lock while another thread blocked on the same
 312 .Nm
 313 lock after acquiring a mutex, then the second thread would effectively
 314 end up sleeping while holding a mutex, which is not allowed.
 315 .Sh SEE ALSO
 316 .Xr locking 9 ,
 317 .Xr lock 9 ,
 318 .Xr mutex 9 ,
 319 .Xr panic 9 ,
 320 .Xr rwlock 9 ,
 321 .Xr sema 9
 322 .Sh BUGS
 323 Currently there is no way to assert that a lock is not held.
 324 This is not possible in the
 325 .No non- Ns Dv WITNESS
 326 case for asserting that this thread
 327 does not hold a shared lock.
 328 In the
 329 .No non- Ns Dv WITNESS
 330 case, the
 331 .Dv SA_LOCKED
 332 and
 333 .Dv SA_SLOCKED
 334 assertions merely check that some thread holds a shared lock.
 335 They do not ensure that the current thread holds a shared lock.