Module Name: src
Committed By: pgoyette
Date: Mon Feb 25 21:43:00 UTC 2019
Modified Files:
src/share/man/man9: localcount.9
Log Message:
Add explicit cross-references to pserialize(9) for the sections about
ensuring that a localcount doesn't disappear while in the process of
being referenced, in the same manner as psref(9).
To generate a diff of this commit:
cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/localcount.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/localcount.9
diff -u src/share/man/man9/localcount.9:1.6 src/share/man/man9/localcount.9:1.7
--- src/share/man/man9/localcount.9:1.6 Fri Jun 2 00:32:12 2017
+++ src/share/man/man9/localcount.9 Mon Feb 25 21:43:00 2019
@@ -1,4 +1,4 @@
-.\" $NetBSD: localcount.9,v 1.6 2017/06/02 00:32:12 chs Exp $
+.\" $NetBSD: localcount.9,v 1.7 2019/02/25 21:43:00 pgoyette Exp $
.\"
.\" Copyright (c) 2016 The NetBSD Foundation
.\" 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 June 1, 2017
+.Dd February 25, 2019
.Dt LOCALCOUNT 9
.Os
.Sh NAME
@@ -86,7 +86,7 @@ network flows) and on which there may be
such as xyzread for a device xyz(4), and short-term fast operations, such as
.Dv xyzioctl(IOC_READ_A_CPU_REG) .
.Sh FUNCTIONS
-.Bl -tag -width 32n
+.Bl -tag -width abcd
.It Fn localcount_init "lc"
Dynamically initialize localcount
.Ar lc
@@ -106,6 +106,13 @@ has been called until it has been re-ini
.It Fn localcount_acquire "lc"
Acquire a reference to the localcount
.Ar lc .
+.Pp
+The caller must ensure by some other mechanism that the localcount will
+not be destroyed before the call to
+.Fn localcount_acquire ;
+typically this will be via a
+.Xr pserialize 9
+read section.
.It Fn localcount_release "lc" "cv" "mtx"
Release a reference to the localcount
.Ar lc .
@@ -140,7 +147,13 @@ before calling
.Fn localcount_drain .
For example, any object that may be found in a list and acquired must be
removed from the list before calling
-.Fn localcount_drain .
+.Fn localcount_drain ;
+removal from the list would typically be protected by calling
+.Xr pserialize_perform 9
+to wait for any
+.Xr pserialize 9
+readers to complete.
+.Pp
Once the localcount object
.Ar lc
is passed to
