Module Name: src
Committed By: jdolecek
Date: Mon Dec 10 19:21:56 UTC 2018
Modified Files:
src/share/man/man9: rwlock.9
Log Message:
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
To generate a diff of this commit:
cvs rdiff -u -r1.17 -r1.18 src/share/man/man9/rwlock.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/rwlock.9
diff -u src/share/man/man9/rwlock.9:1.17 src/share/man/man9/rwlock.9:1.18
--- src/share/man/man9/rwlock.9:1.17 Sun Nov 12 21:14:33 2017
+++ src/share/man/man9/rwlock.9 Mon Dec 10 19:21:56 2018
@@ -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 @@ Otherwise, returns zero.
.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,
