Date: Mon, 20 Jul 2009 04:52:07 GMT From: Ben Kaduk <kaduk@mit.edu> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/136918: grammar fixes to locking.9 Message-ID: <200907200452.n6K4q7P3027879@www.freebsd.org> Resent-Message-ID: <200907200500.n6K50CRW078002@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200907200452.n6K4q7P3027879>