Date: Mon, 15 Feb 2010 17:41:59 +0000 (UTC) From: Edward Tomasz Napierala <trasz@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r203929 - head/share/man/man9 Message-ID: <201002151741.o1FHfxsI069142@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <kaduk at mit dot edu>, Haven Hash <havenster at gmail dot com> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201002151741.o1FHfxsI069142>