Module Name: src
Committed By: riastradh
Date: Wed Apr 1 22:51:33 UTC 2015
Modified Files:
src/share/man/man9: wapbl.9
Log Message:
Clarify what wapbl_jlock_assert and wapbl_junlock_assert mean.
To generate a diff of this commit:
cvs rdiff -u -r1.9 -r1.10 src/share/man/man9/wapbl.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/wapbl.9
diff -u src/share/man/man9/wapbl.9:1.9 src/share/man/man9/wapbl.9:1.10
--- src/share/man/man9/wapbl.9:1.9 Tue Mar 31 00:03:58 2015
+++ src/share/man/man9/wapbl.9 Wed Apr 1 22:51:33 2015
@@ -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 @@ Either all writes issued between
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 @@ that was given to
.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 @@ occur in a single transaction -- there i
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
