docs/136918: grammar fixes to locking.9

Mon Jul 20 05:00:17 UTC 2009

>Number:         136918
>Category:       docs
>Synopsis:       grammar fixes to locking.9
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Jul 20 05:00:12 UTC 2009
>Closed-Date:
>Last-Modified:
>Originator:     Ben Kaduk
>Release:        8-current
>Organization:
MIT SIPB
>Environment:
FreeBSD periphrasis.mit.edu 8.0-CURRENT FreeBSD 8.0-CURRENT #12: Fri Jun 26 23:33:14 EDT 2009     kaduk at periphrasis.mit.edu:/usr/obj/usr/src/sys/PERIPHRASIS  amd64
>Description:
There are a number of grammar errors in the locking.9 man page.

This is basically orthogonal to docs/134074 , and also does not attempt to remedy the lack of a Semaphores section or the lack of content on lockmanager locks.

There is a little bit of markup change and clarity improvement as well.
>How-To-Repeat:
man 9 locking
>Fix:
patch available at
http://stuff.mit.edu/afs/sipb.mit.edu/user/kaduk/freebsd/patches/locking.9.diff.2009.07.20
and inlined below

--- locking.9.orig      2009-07-18 15:15:25.000000000 -0400
+++ locking.9   2009-07-20 00:34:46.000000000 -0400
@@ -77,8 +77,8 @@
 Some of these primitives may be used at the low (interrupt) level and
 some may not.
 .Pp
-There are strict ordering requirements and for some of the types this
-is checked using the
+There are strict ordering requirements for the different lock types,
+and for some of the types this ordering is checked using the
 .Xr witness 4
 code.
 .Pp
@@ -98,9 +98,10 @@
 A non-spin mutex can be considered to be equivalent
 to getting a write lock on an
 .Em rw_lock
-(see below), and in fact non-spin mutexes and rw_locks may soon become the same thing.
-As in spin mutexes, you either get it or you don't.
-You may only call the
+(see below), and in fact non-spin mutexes and rw_locks
+may soon become the same thing.
+As for spin mutexes, you either get it or you don't.
+While holding a mutex, you may only call the
 .Xr sleep 9
 call via
 .Fn msleep
@@ -111,20 +112,22 @@
 as part of waking up.
 This is often however a
 .Em BAD
-idea because it generally relies on you having
+idea because it generally relies on you the programmer having
 such a good knowledge of all the call graph above you
-and what assumptions it is making that there are a lot
+and what assumptions the calling code has made that there are a lot
 of ways to make hard-to-find mistakes.
-For example you MUST re-test all the assumptions you made before,
-all the way up the call graph to where you got the lock.
-You can not just assume that mtx_sleep can be inserted anywhere.
-If any caller above you has any mutex or
-rwlock, your sleep, will cause a panic.
+For example you MUST re-test all the assumptions that were made before
+acquiring the lock, in all the levels of the call graph.
+You can not just assume that a
+.Fn mtx_sleep
+can be inserted anywhere.
+If any caller above you holds any mutex or
+rwlock, your sleep will cause a panic.
 If the sleep only happens rarely it may be years before the
 bad code path is found.
 .Ss Pool Mutexes
-A variant of regular mutexes where the allocation of the mutex is handled
-more by the system.
+A variant of regular mutexes where the allocation of the mutex is
+largely handled by the system.
 .Ss Rw_locks
 Reader/writer locks allow shared access to protected data by multiple threads,
 or exclusive access by a single thread.
@@ -173,7 +176,7 @@
 locking.
 .Em rm_lock
 locks implement full priority propagation by tracking shared owners
-using a lock user supplied
+using a caller-supplied
 .Em tracker
 data structure.
 .Ss Sx_locks
@@ -205,11 +208,12 @@
 Turnstiles are used to hold a queue of threads blocked on
 non-sleepable locks.
 Sleepable locks use condition variables to implement their queues.
-Turnstiles differ from a sleep queue in that turnstile queue's
-are assigned to a lock held by an owning thread.
-Thus, when one thread is enqueued onto a turnstile, it can lend its
-priority to the owning thread.
-If this sounds confusing, we need to describe it better.
+Turnstiles differ from sleep queues in that turnstile queues
+are assigned to a lock held by an owning thread, whereas
+there is a global hash table of active sleep queues
+Thus, when a thread running at a high priority is enqueued onto
+a turnstile, its priority can propagate to the thread that holds
+the lock, helping to avoid a deadlock situation.
 .Ss Semaphores
 .Ss Condition variables
 Condition variables are used in conjunction with mutexes to wait for
@@ -329,7 +333,7 @@
 Lock order is important.
 .Pp
 .Em *3
-There are calls atomically release this primitive when going to sleep
+There are calls that atomically release this primitive when going to sleep
 and reacquire it on wakeup (e.g.
 .Fn mtx_sleep ,
 .Fn rw_sleep


>Release-Note:
>Audit-Trail:
>Unformatted:

