From owner-svn-src-all@FreeBSD.ORG Mon Feb 15 17:41:59 2010 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A169B1065676; Mon, 15 Feb 2010 17:41:59 +0000 (UTC) (envelope-from trasz@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 90FD68FC18; Mon, 15 Feb 2010 17:41:59 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o1FHfxDP069144; Mon, 15 Feb 2010 17:41:59 GMT (envelope-from trasz@svn.freebsd.org) Received: (from trasz@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o1FHfxsI069142; Mon, 15 Feb 2010 17:41:59 GMT (envelope-from trasz@svn.freebsd.org) Message-Id: <201002151741.o1FHfxsI069142@svn.freebsd.org> From: Edward Tomasz Napierala Date: Mon, 15 Feb 2010 17:41:59 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r203929 - head/share/man/man9 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 15 Feb 2010 17:41:59 -0000 Author: trasz Date: Mon Feb 15 17:41:59 2010 New Revision: 203929 URL: http://svn.freebsd.org/changeset/base/203929 Log: Some rewording and language fixes. PR: docs/136918, docs/134074 Submitted by: Ben Kaduk , Haven Hash Modified: head/share/man/man9/locking.9 Modified: head/share/man/man9/locking.9 ============================================================================== --- head/share/man/man9/locking.9 Mon Feb 15 16:41:30 2010 (r203928) +++ head/share/man/man9/locking.9 Mon Feb 15 17:41:59 2010 (r203929) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 13, 2010 +.Dd February 15, 2010 .Dt LOCKING 9 .Os .Sh NAME @@ -106,7 +106,7 @@ Mostly reader locks are similar to locks but optimized for very infrequent write locking. .Em Read-mostly locks implement full priority propagation by tracking shared owners -using a lock user supplied +using a caller-supplied .Em tracker data structure. .Pp @@ -272,24 +272,18 @@ holding mutex, or to try to allocate mem read-write lock. .Pp As a special case, it is possible to call -.Fn sleep 9 +.Fn sleep or -.Fn mtx_sleep 9 -while holding a mutex. -It will atomically drop the mutex and reacquire it -as part of waking up. -This is often however a bad -idea because it generally relies on you having -such a good knowledge of all the call graph above you -and what assumptions it is making 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. -If the sleep only happens rarely it may be years before the -bad code path is found. +.Fn mtx_sleep +while holding a single mutex. +It will atomically drop that mutex and reacquire it as part of waking up. +This is often a bad idea because it generally relies on the programmer having +good knowledge of all of the call graph above the place where +.Fn mtx_sleep +is being called and assumptions the calling code has made. +Because the lock gets dropped during sleep, one one must re-test all +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. @@ -315,11 +309,11 @@ Recursion is defined per lock. Lock order is important. .Pp .Em *2 -readers can recurse though writers can not. +Readers can recurse though writers can not. 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 @@ -330,7 +324,7 @@ and .Em *4 Though one can sleep holding an sx lock, one can also use .Fn sx_sleep -which atomically release this primitive when going to sleep and +which will atomically release this primitive when going to sleep and reacquire it on wakeup. .Ss Context mode table The next table shows what can be used in different contexts. @@ -345,6 +339,7 @@ At this time this is a rather easy to re .It syscall: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok .El .Sh SEE ALSO +.Xr witness 4 , .Xr condvar 9 , .Xr lock 9 , .Xr mtx_pool 9 , @@ -354,7 +349,6 @@ At this time this is a rather easy to re .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 , -.Xr witness 9 , .Xr LOCK_PROFILING 9 .Sh HISTORY These