[src/trunk]: src/share/man/man9 clarify how rw_{write,read,lock}_held() work; ...

[jdolecek <jdolecek%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a42d89bad02c
branches:  trunk
changeset: 837555:a42d89bad02c
user:      jdolecek <jdolecek%NetBSD.org@localhost>
date:      Mon Dec 10 19:21:56 2018 +0000

description:
clarify how rw_{write,read,lock}_held() work; rw_write_held() actually
returns non-zero only if current lwp is the owner, the other two don't care
about owner; also warn that functions are not atomic, and thus should only
ever be used to assert that the lock is held

diffstat:

 share/man/man9/rwlock.9 |  21 ++++++++++++++++-----
 1 files changed, 16 insertions(+), 5 deletions(-)

diffs (48 lines):

diff -r 31d8f2cd62a4 -r a42d89bad02c share/man/man9/rwlock.9
--- a/share/man/man9/rwlock.9   Mon Dec 10 16:28:52 2018 +0000
+++ b/share/man/man9/rwlock.9   Mon Dec 10 19:21:56 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: rwlock.9,v 1.17 2017/11/12 21:14:33 riastradh Exp $
+.\"    $NetBSD: rwlock.9,v 1.18 2018/12/10 19:21:56 jdolecek Exp $
 .\"
 .\" Copyright (c) 2006, 2007, 2009 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 22, 2009
+.Dd December 10, 2018
 .Dt RWLOCK 9
 .Os
 .Sh NAME
@@ -168,15 +168,26 @@
 .Pp
 Downgrade a lock from a write hold to a read hold.
 .It Fn rw_write_held "rw"
+.Pp
+Return non-zero if write lock is held by current lwp.
+Otherwise, return zero.
 .It Fn rw_read_held "rw"
+Returns non-zero if read lock is held by any lwp.
+Otherwise, return zero.
 .It Fn rw_lock_held "rw"
 .Pp
-Test the lock's condition and return non-zero if the lock is held
-(potentially by the current LWP) and matches the specified condition.
+Returns non-zero if either read or write lock is held by any lwp.
 Otherwise, return zero.
 .Pp
-These functions must never be used to make locking decisions at run time:
+Functions
+.Fn rw_write_held ,
+.Fn rw_read_held ,
+and
+.Fn rw_lock_held
+must never be used to make locking decisions at run time:
 they are provided only for diagnostic purposes.
+They are also not atomic, hence they should only be used to assert
+that lock is held.
 .El
 .Sh PERFORMANCE CONSIDERATIONS
 RW locks are subject to high cache contention on multiprocessor systems,