[src/trunk]: src/share/man/man9 Clarify what wapbl_jlock_assert and wapbl_jun...

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

details:   https://anonhg.NetBSD.org/src/rev/2733bf2192f1
branches:  trunk
changeset: 337092:2733bf2192f1
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Wed Apr 01 22:51:33 2015 +0000

description:
Clarify what wapbl_jlock_assert and wapbl_junlock_assert mean.

diffstat:

 share/man/man9/wapbl.9 |  40 ++++++++++++++++++++++++++++++++++++----
 1 files changed, 36 insertions(+), 4 deletions(-)

diffs (70 lines):

diff -r 859bc7eba396 -r 2733bf2192f1 share/man/man9/wapbl.9
--- a/share/man/man9/wapbl.9    Wed Apr 01 21:59:01 2015 +0000
+++ b/share/man/man9/wapbl.9    Wed Apr 01 22:51:33 2015 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: wapbl.9,v 1.9 2015/03/31 00:03:58 riastradh Exp $
+.\"    $NetBSD: wapbl.9,v 1.10 2015/04/01 22:51:33 riastradh Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -168,9 +168,9 @@
 and
 .Fn wapbl_end
 will complete, or none of them will.
-File systems can assert that the transaction should be locked with
+File systems can assert that the transaction is locked with
 .Fn wapbl_jlock_assert ,
-or unlocked, with
+or not exclusively locked, with
 .Fn wapbl_junlock_assert .
 .Pp
 If a file system requires multiple transactions to initialize an
@@ -399,8 +399,33 @@
 .Fn wapbl_start .
 .It Fn wapbl_jlock_assert wl
 Assert that the current transaction is locked.
+.Pp
+Note that it might not be locked by the current thread: this assertion
+passes if
+.Em any
+thread has it locked.
 .It Fn wapbl_junlock_assert wl
-Assert that the current transaction is unlocked.
+Assert that the current transaction is not exclusively locked by the
+current thread.
+.Pp
+Users of
+.Nm
+observe exclusive locks only in the
+.Fa flushfn
+and
+.Fa flushabortfn
+callbacks to
+.Fn wapbl_start .
+Outside of such contexts, the transaction is never exclusively locked,
+even between
+.Fn wapbl_begin
+and
+.Fn wapbl_end .
+.Pp
+There is no way to assert that the current transaction is not locked at
+all -- i.e., that the caller may lock the transaction with
+.Fn wapbl_begin
+without danger of deadlock.
 .El
 .Sh CODE REFERENCES
 The
@@ -465,6 +490,13 @@
 block allocations if the write fails in the middle, e.g. because of a
 fault in the middle of the user buffer.
 .Pp
+.Fn wapbl_jlock_assert
+does not guarantee that the current thread has the current transaction
+locked.
+.Fn wapbl_junlock_assert
+does not guarantee that the current thread does not have the current
+transaction locked at all.
+.Pp
 There is only one
 .Nm
 transaction for each file system at any given time, and only one