--- 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
