share/man/man9/locking.9

   1 .\" Copyright (c) 2007 Julian Elischer  (julian -  freebsd org )
   2 .\" 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, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd March 14, 2007
  28 .Dt LOCKING 9
  29 .Os
  30 .Sh NAME
  31 .Nm locking ,
  32 .Nd kernel synchronization primitives
  33 .Sh SYNOPSIS
  34 All sorts of stuff to go here.
  35 .Pp
  36 .Sh DESCRIPTION
  37 The
  38 .Em FreeBSD
  39 kernel is written to run across multiple CPUs and as such requires
  40 several different sychronization primatives to allow the developers
  41 to safely access and manipulate the many data types required.
  42 .Pp
  43 These include:
  44 .Bl -enum
  45 .It
  46 Spin Mutexes
  47 .It
  48 Sleep Mutexes
  49 .It
  50 pool Mutexes
  51 .It
  52 Shared-Exclusive locks
  53 .It
  54 Reader-Writer locks
  55 .It
  56 Turnstyles
  57 .It
  58 Semaphores
  59 .It
  60 Condition variables
  61 .It
  62 Sleep/wakeup
  63 .It
  64 Giant
  65 .It
  66 Lockmanager locks
  67 .El
  68 .Pp
  69 The primnatives interact and have a number of rules regarding how
  70 they can and can not be combined. Ther eare too many for the average humanmind and they
  71 keep changing. (if you disagree, please write replacement text)  :-)
  72 .Pp
  73 Some of these primatives may be used at the low (interrupt) level and some may not.
  74 .Pp
  75 There are strict ordering requirements and for some of the types this
  76 is checked using the
  77 .Xr witness 4
  78 code.
  79 .Pp
  80 .Ss SPIN Mutexes
  81 Mutexes are the basic primative.
  82 You either hold it or you don't.
  83 If you don't own it then you just spin, waiting for the holder (on another CPU)
  84 to release it. Hopefully they are doing something fast. You can not do anythign that
  85 deschedules the thread while you are holding a SPIN mutex.
  86 .Ss Sleep Mutexes
  87 Basically sleep (regular) mutexes will deschedule the thread if
  88 the mutex can not be acquired. As in spin mutexes, you either get it or you don't.
  89 You may call the
  90 .Xr sleep 9
  91 call
  92 .Fn msleep
  93 or the new
  94 .Fn mtx_sleep
  95 variant. These will atomically drop the mutex and reacquire it
  96 as part of waking up.
  97 .Ss Pool Mutexes
  98 A variant of SLEEP mutexes where the allocation of the mutex is handled more by the system.
  99 .Ss Sx_locks
 100 Shared/exclusive locks are used to protect data that are read far more often
 101 than they are written.
 102 Mutexes are inherently more efficient than shared/exclusive locks, so
 103 shared/exclusive locks should be used prudently.
 104 A thread may hold a shared or exclusive lock on an
 105 .Em sx_lock
 106 lock while sleeping.
 107 As a result, an
 108 .Em sx_lockm
 109 lock may not be acquired while holding a mutex.
 110 Otherwise, if one thread slept while holding an
 111 .Em sx_lockm
 112 lock while another thread blocked on the same
 113 .Em sx_lockm
 114 lock after acquiring a mutex, then the second thread would effectively
 115 end up sleeping while holding a mutex, which is not allowed.
 116 .Ss Rw_locks
 117 Reader/writer locks allow shared access to protected data by multiple threads,
 118 or exclusive access by a single thread.
 119 The threads with shared access are known as
 120 .Em readers
 121 since they only read the protected data.
 122 A thread with exclusive access is known as a
 123 .Em writer
 124 since it can modify protected data.
 125 .Pp
 126 Although reader/writer locks look very similar to
 127 .Xr sx 9
 128 locks, their usage pattern is different.
 129 Reader/writer locks can be treated as mutexes (see
 130 .Xr mutex 9 )
 131 with shared/exclusive semantics.
 132 Unlike
 133 .Xr sx 9 ,
 134 an
 135 .Em rw_lock
 136 can be locked while holding a non-spin mutex, and an
 137 .Em rw_lock
 138 cannot be held while sleeping.
 139 The
 140 .Em rw_lock
 141 locks have priority propagation like mutexes, but priority
 142 can be propagated only to an exclusive holder.
 143 This limitation comes from the fact that shared owners
 144 are anonymous.
 145 Another important property is that shared holders of
 146 .Em rw_lock
 147 can recurse,
 148 but exclusive locks are not allowed to recurse.
 149 .Ss Turnstyless
 150 Turnstiles are used to hold a queue of threads blocked on
 151 non-sleepable locks.  Sleepable locks use condition variables to
 152 implement their queues.  Turnstiles differ from a sleep queue in that
 153 turnstile queue's are assigned to a lock held by an owning thread.  Thus,
 154 when one thread is enqueued onto a turnstile, it can lend its priority
 155 to the owning thread.
 156 .Ss Semaphores
 157 .Ss Condition variables
 158 Condition variables are used in conjunction with mutexes to wait for conditions
 159 to occur.
 160 A thread must hold the mutex before calling the
 161 .Fn cv_wait* ,
 162 functions.
 163 When a thread waits on a condition, the mutex
 164 is atomically released before the thread is blocked, then reacquired
 165 before the function call returns.
 166 .Ss Giant
 167 Giant is a special instance of a sleep lock.
 168 it has several special characteristics.
 169 .Ss Sleep/wakeup
 170 The functions
 171 .Fn tsleep ,
 172 .Fn msleep ,
 173 .Fn msleep_spin ,
 174 .Fn pause ,
 175 .Fn wakeup ,
 176 and
 177 .Fn wakeup_one
 178 handle event-based thread blocking.
 179 If a thread must wait for an
 180 external event, it is put to sleep by
 181 .Fn tsleep ,
 182 .Fn msleep ,
 183 .Fn msleep_spin ,
 184 or
 185 .Fn pause .
 186 Threads may also wait using one of the locking primitive sleep routines
 187 .Xr mtx_sleep 9 ,
 188 .Xr rw_sleep 9 ,
 189 or
 190 .Xr sx_sleep 9 .
 191 .Pp
 192 The parameter
 193 .Fa chan
 194 is an arbitrary address that uniquely identifies the event on which
 195 the thread is being put to sleep.
 196 All threads sleeping on a single
 197 .Fa chan
 198 are woken up later by
 199 .Fn wakeup ,
 200 often called from inside an interrupt routine, to indicate that the
 201 resource the thread was blocking on is available now.
 202 .Pp
 203 Several of the sleep functions including
 204 .Fn msleep ,
 205 .Fn msleep_spin ,
 206 and the locking primitive sleep routines specify an additional lock
 207 parameter.
 208 The lock will be released before sleeping and reacquired
 209 before the sleep routine returns.
 210 If
 211 .Fa priority
 212 includes the
 213 .Dv PDROP
 214 flag, then
 215 the lock will not be reacquired before returning.
 216 The lock is used to ensure that a condition can be checked atomically,
 217 and that the current thread can be suspended without missing a
 218 change to the condition, or an associated wakeup.
 219 In addition, all of the sleep routines will fully drop the
 220 .Va Giant
 221 mutex
 222 (even if recursed)
 223 while the thread is suspended and will reacquire the
 224 .Va Giant
 225 mutex before the function returns.
 226 .Pp
 227 .Ss lockmanager locks
 228 Largly deprecated. See the
 229 .Xr lock 9
 230 page for more information.
 231 I don't know what the downsides are but I'm sure someone will fill in this part.
 232 .Sh Usage tables.
 233 .Ss Interaction table.
 234 The following table shows what you can and can not do if you hold
 235 one of the synchronisation primatives discussed here:
 236 (someone who knows what they are talking about should write this table)
 237 .Bl -column ".Ic xxxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXX" -offset indent
 238 .It Xo
 239 .Em "You have:  You want:" Ta Spin_mtx Ta Slp_mtx Ta sx_lock Ta rw_lock Ta sleep
 240 .Xc
 241 .It Ic SPIN mutex  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no-3
 242 .It Ic Sleep mutex Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&no-3
 243 .It Ic sx_lock     Ta \&ok Ta \&no Ta \&ok-2 Ta \&no Ta \&ok-4
 244 .It Ic rw_lock     Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&no-3
 245 .El
 246 .Pp
 247 .Em *1
 248 Recursion is defined per lock. lock order is important.
 249 .Pp
 250 .Em *2
 251 readers can recurse tough writers can not. lock order is important.
 252 .Pp
 253 .Em *3
 254 There are calls atomically release this primative when going to sleep
 255 and reacquire it on wakeup (e.g.
 256 .Fn mtx_sleep ,
 257 .Fn rw_sleep
 258 and
 259 .Fn msleep_spin ).
 260 .Pp
 261 .Em *4
 262 Though one can sleep holding an sx lock, one can also use
 263 .Fn sx_sleep
 264 which atomically release this primative when going to sleep and reacquire it on wakeup.
 265 .Ss Context mode table.
 266 The next table shows what can be used in differnt contexts. at this time this is a
 267 rather easy to remember table.
 268 .Bl -column ".Ic Xxxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXX" -offset indent
 269 .It Xo
 270 .Em "Context:" Ta Spin_mtx Ta Slp_mtx Ta sx_lock Ta rw_lock Ta sleep
 271 .Xc
 272 .It interrupt:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no
 273 .It idle:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no
 274 .El
 275 .Xc
 276 .Sh SEE ALSO
 277 .Xr condvar 9 ,
 278 .Xr lock 9
 279 .Xr mtx_pool 9 ,
 280 .Xr rwlock 9 ,
 281 .Xr sema 9 ,
 282 .Xr sleep 9 ,
 283 .Xr sx 9
 284 .Xr LOCK_PROFILING 9 ,
 285 .Xr WITNESS 9 ,
 286 .Sh HISTORY
 287 These
 288 functions appeared in
 289 .Bsx 4.1
 290 through
 291 .Fx 7.0