Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 27 Jun 2012 01:13:37 +0000 (UTC)
From:      Julian Elischer <julian@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r237619 - head/share/man/man9
Message-ID:  <201206270113.q5R1DbZ2073007@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: julian
Date: Wed Jun 27 01:13:37 2012
New Revision: 237619
URL: http://svn.freebsd.org/changeset/base/237619

Log:
  Try clean up some of my original text and neaten a table.
  
  MFC after:	1 week

Modified:
  head/share/man/man9/locking.9

Modified: head/share/man/man9/locking.9
==============================================================================
--- head/share/man/man9/locking.9	Wed Jun 27 00:50:25 2012	(r237618)
+++ head/share/man/man9/locking.9	Wed Jun 27 01:13:37 2012	(r237619)
@@ -37,11 +37,19 @@ kernel is written to run across multiple
 several different synchronization primitives to allow the developers
 to safely access and manipulate the many data types required.
 .Ss Mutexes
-Mutexes (also called "sleep mutexes") are the most commonly used
+Mutexes (also erroneously called "sleep mutexes") are the most commonly used
 synchronization primitive in the kernel.
-Thread acquires (locks) a mutex before accessing data shared with other
+A thread acquires (locks) a mutex before accessing data shared with other
 threads (including interrupt threads), and releases (unlocks) it afterwards.
-If the mutex cannot be acquired, the thread requesting it will sleep.
+If the mutex cannot be acquired, the thread requesting it will wait.
+Mutexes are by default adaptive, meaning that
+if the owner of a contended mutex is currently running on another CPU,
+then a thread attempting to acquire the mutex will briefly spin
+in the hope that the owner is only briefly holding it,
+and might release it shortly.
+If the owner does not do so, the waiting thread proceeds to yield the processor,
+allowing other threads to run.
+If the owner is not currently actually running then the spin step is skipped.
 Mutexes fully support priority propagation.
 .Pp
 See
@@ -49,9 +57,10 @@ See
 for details.
 .Ss Spin mutexes
 Spin mutexes are variation of basic mutexes; the main difference between
-the two is that spin mutexes never sleep - instead, they spin, waiting
-for the thread holding the lock, which runs on another CPU, to release it.
-Differently from ordinary mutex, spin mutexes disable interrupts when acquired.
+the two is that spin mutexes never yield the processor - instead, they spin,
+waiting for the thread holding the lock,
+(which must be running on another CPU), to release it.
+Spin mutexes disable interrupts while the held so as to not get pre-empted.
 Since disabling interrupts is expensive, they are also generally slower.
 Spin mutexes should be used only when necessary, e.g. to protect data shared
 with interrupt filter code (see
@@ -122,7 +131,7 @@ and read-mostly locks.
 They don't support priority propagation.
 They should be considered to be closely related to
 .Xr sleep 9 .
-In fact it could in some cases be
+They could in some cases be
 considered a conditional sleep.
 .Pp
 See
@@ -146,8 +155,8 @@ A thread must hold the mutex before call
 .Fn cv_wait* ,
 functions.
 When a thread waits on a condition, the mutex
-is atomically released before the thread is blocked, then reacquired
-before the function call returns.
+is atomically released before the thread thread yields the processor,
+then reacquired before the function call returns.
 .Pp
 See
 .Xr condvar 9
@@ -255,14 +264,14 @@ Many of these rules are checked using th
 .Xr witness 4
 code.
 .Ss Bounded vs. unbounded sleep
-The following primitives perform bounded sleep: mutexes, pool mutexes,
-reader/writer locks and read-mostly locks.
+The following primitives perform bounded sleep:
+ mutexes, pool mutexes, reader/writer locks and read-mostly locks.
 .Pp
-The following primitives block (perform unbounded sleep): shared/exclusive locks,
-counting semaphores, condition variables, sleep/wakeup and lockmanager locks.
+The following primitives may perform an unbounded sleep:
+shared/exclusive locks, counting semaphores, condition variables, sleep/wakeup and lockmanager locks.
 .Pp
-It is an error to do any operation that could result in any kind of sleep while
-holding spin mutex.
+It is an error to do any operation that could result in yielding the processor
+while holding a spin mutex.
 .Pp
 As a general rule, it is an error to do any operation that could result
 in unbounded sleep while holding any primitive from the 'bounded sleep' group.
@@ -284,21 +293,22 @@ Because the lock gets dropped during sle
 the assumptions that were made before, all the way up the call graph to the
 place where the lock was acquired.
 .Pp
-It is an error to do any operation that could result in any kind of sleep when
-running inside an interrupt filter.
+It is an error to do any operation that could result in yielding of
+the processor when running inside an interrupt filter.
 .Pp
 It is an error to do any operation that could result in unbounded sleep when
 running inside an interrupt thread.
 .Ss Interaction table
 The following table shows what you can and can not do while holding
 one of the synchronization primitives discussed:
-.Bl -column ".Ic xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
-.It Em "You have: You want:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
+.Bl -column ".Ic xxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
+.It Em "       You want:" Ta spin-mtx Ta mutex Ta rwlock Ta rmlock Ta sx Ta sleep
+.It Em "You have:     " Ta ------ Ta ------ Ta ------ Ta ------ Ta ------ Ta ------
 .It spin mtx  Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3
-.It mutex     Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3
-.It sx        Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4
-.It rwlock    Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3
-.It rmlock    Ta \&ok Ta \&ok Ta \&no-5 Ta \&ok Ta \&ok-2 Ta \&no-5
+.It mutex     Ta \&ok Ta \&ok-1 Ta \&ok Ta \&ok Ta \&no Ta \&no-3
+.It rwlock    Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&no Ta \&no-3
+.It rmlock    Ta \&ok Ta \&ok Ta \&ok Ta \&ok-2 Ta \&no-5 Ta \&no-5
+.It sx        Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&no-2 Ta \&ok-4
 .El
 .Pp
 .Em *1



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201206270113.q5R1DbZ2073007>