From owner-freebsd-doc@FreeBSD.ORG Mon Jul 20 05:00:17 2009 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 1B9381065673 for ; Mon, 20 Jul 2009 05:00:17 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 6FDFC8FC12 for ; Mon, 20 Jul 2009 05:00:12 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.3/8.14.3) with ESMTP id n6K50CIw078003 for ; Mon, 20 Jul 2009 05:00:12 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.3/8.14.3/Submit) id n6K50CRW078002; Mon, 20 Jul 2009 05:00:12 GMT (envelope-from gnats) Resent-Date: Mon, 20 Jul 2009 05:00:12 GMT Resent-Message-Id: <200907200500.n6K50CRW078002@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Ben Kaduk Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 01F0F106566B for ; Mon, 20 Jul 2009 04:52:08 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21]) by mx1.freebsd.org (Postfix) with ESMTP id E3B9D8FC20 for ; Mon, 20 Jul 2009 04:52:07 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n6K4q7aJ027880 for ; Mon, 20 Jul 2009 04:52:07 GMT (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.14.3/8.14.3/Submit) id n6K4q7P3027879; Mon, 20 Jul 2009 04:52:07 GMT (envelope-from nobody) Message-Id: <200907200452.n6K4q7P3027879@www.freebsd.org> Date: Mon, 20 Jul 2009 04:52:07 GMT From: Ben Kaduk To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Cc: Subject: docs/136918: grammar fixes to locking.9 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Jul 2009 05:00:17 -0000 >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: