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