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 synchronization primitives 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 Turnstiles
  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 primitives interact and have a number of rules regarding how
  70 they can and can not be combined. There are too many for the average
  71 human mind and they keep changing.
  72 (if you disagree, please write replacement text)  :-)
  73 .Pp
  74 Some of these primitives may be used at the low (interrupt) level and
  75 some may not.
  76 .Pp
  77 There are strict ordering requirements and for some of the types this
  78 is checked using the
  79 .Xr witness 4
  80 code.
  81 .Pp
  82 .Ss SPIN Mutexes
  83 Mutexes are the basic primitive.
  84 You either hold it or you don't.
  85 If you don't own it then you just spin, waiting for the holder (on
  86 another CPU) to release it.
  87 Hopefully they are doing something fast.
  88 You can not do anything that deschedules the thread while you
  89 are holding a SPIN mutex.
  90 .Ss Sleep Mutexes
  91 Basically sleep (regular) mutexes will deschedule the thread if the
  92 mutex can not be acquired.
  93 As in spin mutexes, you either get it or you don't.
  94 You may call the
  95 .Xr sleep 9
  96 call
  97 .Fn msleep
  98 or the new
  99 .Fn mtx_sleep
 100 variant. These will atomically drop the mutex and reacquire it
 101 as part of waking up.
 102 .Ss Pool Mutexes
 103 A variant of SLEEP mutexes where the allocation of the mutex is handled
 104 more by the system.
 105 .Ss Sx_locks
 106 Shared/exclusive locks are used to protect data that are read far more often
 107 than they are written.
 108 Mutexes are inherently more efficient than shared/exclusive locks, so
 109 shared/exclusive locks should be used prudently.
 110 A thread may hold a shared or exclusive lock on an
 111 .Em sx_lock
 112 lock while sleeping.
 113 As a result, an
 114 .Em sx_lock
 115 lock may not be acquired while holding a mutex.
 116 Otherwise, if one thread slept while holding an
 117 .Em sx_lock
 118 lock while another thread blocked on the same
 119 .Em sx_lock
 120 lock after acquiring a mutex, then the second thread would effectively
 121 end up sleeping while holding a mutex, which is not allowed.
 122 .Ss Rw_locks
 123 Reader/writer locks allow shared access to protected data by multiple threads,
 124 or exclusive access by a single thread.
 125 The threads with shared access are known as
 126 .Em readers
 127 since they only read the protected data.
 128 A thread with exclusive access is known as a
 129 .Em writer
 130 since it can modify protected data.
 131 .Pp
 132 Although reader/writer locks look very similar to
 133 .Xr sx 9
 134 locks, their usage pattern is different.
 135 Reader/writer locks can be treated as mutexes (see
 136 .Xr mutex 9 )
 137 with shared/exclusive semantics.
 138 Unlike
 139 .Xr sx 9 ,
 140 an
 141 .Em rw_lock
 142 can be locked while holding a non-spin mutex, and an
 143 .Em rw_lock
 144 cannot be held while sleeping.
 145 The
 146 .Em rw_lock
 147 locks have priority propagation like mutexes, but priority
 148 can be propagated only to an exclusive holder.
 149 This limitation comes from the fact that shared owners
 150 are anonymous.
 151 Another important property is that shared holders of
 152 .Em rw_lock
 153 can recurse,
 154 but exclusive locks are not allowed to recurse.
 155 .Ss Turnstiles
 156 Turnstiles are used to hold a queue of threads blocked on
 157 non-sleepable locks.
 158 Sleepable locks use condition variables to implement their queues.
 159 Turnstiles differ from a sleep queue in that turnstile queue's
 160 are assigned to a lock held by an owning thread.
 161 Thus, when one thread is enqueued onto a turnstile, it can lend its
 162 priority to the owning thread.
 163 .Ss Semaphores
 164 .Ss Condition variables
 165 Condition variables are used in conjunction with mutexes to wait for
 166 conditions to occur.
 167 A thread must hold the mutex before calling the
 168 .Fn cv_wait* ,
 169 functions.
 170 When a thread waits on a condition, the mutex
 171 is atomically released before the thread is blocked, then reacquired
 172 before the function call returns.
 173 .Ss Giant
 174 Giant is a special instance of a sleep lock.
 175 It has several special characteristics.
 176 .Bl -enum
 177 .It
 178 It is recursive.
 179 .It
 180 Drivers can request that Giant be locked around them, but this is
 181 going away.
 182 .It
 183 You can sleep while it has recursed, but other recursive locks cannot.
 184 .It
 185 Giant must be locked first.
 186 .It
 187 There are places in the kernel that drop Giant and pick it back up
 188 again.
 189 Sleep locks will do this before sleeping.
 190 Parts of the Network or VM code may do this as well, depending on the
 191 setting of a sysctl.
 192 This means that you cannot count on Giant keeping other code from
 193 running if your code sleeps, even if you want it to.
 194 .El
 195 .Ss Sleep/wakeup
 196 The functions
 197 .Fn tsleep ,
 198 .Fn msleep ,
 199 .Fn msleep_spin ,
 200 .Fn pause ,
 201 .Fn wakeup ,
 202 and
 203 .Fn wakeup_one
 204 handle event-based thread blocking.
 205 If a thread must wait for an external event, it is put to sleep by
 206 .Fn tsleep ,
 207 .Fn msleep ,
 208 .Fn msleep_spin ,
 209 or
 210 .Fn pause .
 211 Threads may also wait using one of the locking primitive sleep routines
 212 .Xr mtx_sleep 9 ,
 213 .Xr rw_sleep 9 ,
 214 or
 215 .Xr sx_sleep 9 .
 216 .Pp
 217 The parameter
 218 .Fa chan
 219 is an arbitrary address that uniquely identifies the event on which
 220 the thread is being put to sleep.
 221 All threads sleeping on a single
 222 .Fa chan
 223 are woken up later by
 224 .Fn wakeup ,
 225 often called from inside an interrupt routine, to indicate that the
 226 resource the thread was blocking on is available now.
 227 .Pp
 228 Several of the sleep functions including
 229 .Fn msleep ,
 230 .Fn msleep_spin ,
 231 and the locking primitive sleep routines specify an additional lock
 232 parameter.
 233 The lock will be released before sleeping and reacquired
 234 before the sleep routine returns.
 235 If
 236 .Fa priority
 237 includes the
 238 .Dv PDROP
 239 flag, then the lock will not be reacquired before returning.
 240 The lock is used to ensure that a condition can be checked atomically,
 241 and that the current thread can be suspended without missing a
 242 change to the condition, or an associated wakeup.
 243 In addition, all of the sleep routines will fully drop the
 244 .Va Giant
 245 mutex
 246 (even if recursed)
 247 while the thread is suspended and will reacquire the
 248 .Va Giant
 249 mutex before the function returns.
 250 .Pp
 251 .Ss lockmanager locks
 252 Largely deprecated. See the
 253 .Xr lock 9
 254 page for more information.
 255 I don't know what the downsides are but I'm sure someone will fill in this part.
 256 .Sh Usage tables.
 257 .Ss Interaction table.
 258 The following table shows what you can and can not do if you hold
 259 one of the synchronization primitives discussed here:
 260 (someone who knows what they are talking about should write this table)
 261 .Bl -column ".Ic xxxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXX" -offset indent
 262 .It Xo
 263 .Em "You have:  You want:" Ta Spin_mtx Ta Slp_mtx Ta sx_lock Ta rw_lock Ta sleep
 264 .Xc
 265 .It Ic SPIN mutex  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no-3
 266 .It Ic Sleep mutex Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&no-3
 267 .It Ic sx_lock     Ta \&ok Ta \&no Ta \&ok-2 Ta \&no Ta \&ok-4
 268 .It Ic rw_lock     Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&no-3
 269 .El
 270 .Pp
 271 .Em *1
 272 Recursion is defined per lock. Lock order is important.
 273 .Pp
 274 .Em *2
 275 readers can recurse though writers can not. Lock order is important.
 276 .Pp
 277 .Em *3
 278 There are calls atomically release this primitive when going to sleep
 279 and reacquire it on wakeup (e.g.
 280 .Fn mtx_sleep ,
 281 .Fn rw_sleep
 282 and
 283 .Fn msleep_spin
 284 ).
 285 .Pp
 286 .Em *4
 287 Though one can sleep holding an sx lock, one can also use
 288 .Fn sx_sleep
 289 which atomically release this primitive when going to sleep and
 290 reacquire it on wakeup.
 291 .Ss Context mode table.
 292 The next table shows what can be used in different contexts.
 293 At this time this is a rather easy to remember table.
 294 .Bl -column ".Ic Xxxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXX" -offset indent
 295 .It Xo
 296 .Em "Context:" Ta Spin_mtx Ta Slp_mtx Ta sx_lock Ta rw_lock Ta sleep
 297 .Xc
 298 .It interrupt:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no
 299 .It idle:  Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no
 300 .El
 301 .Sh SEE ALSO
 302 .Xr condvar 9 ,
 303 .Xr lock 9
 304 .Xr mtx_pool 9 ,
 305 .Xr rwlock 9 ,
 306 .Xr sema 9 ,
 307 .Xr sleep 9 ,
 308 .Xr sx 9
 309 .Xr LOCK_PROFILING 9 ,
 310 .Xr WITNESS 9 ,
 311 .Sh HISTORY
 312 These
 313 functions appeared in
 314 .Bsx 4.1
 315 through
 316 .Fx 7.0