[src/trunk]: src/share/man/man9 Add explicit cross-references to pserialize(9...

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

details:   https://anonhg.NetBSD.org/src/rev/a3e5e5788e4e
branches:  trunk
changeset: 449196:a3e5e5788e4e
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Mon Feb 25 21:43:00 2019 +0000

description:
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).

diffstat:

 share/man/man9/localcount.9 |  21 +++++++++++++++++----
 1 files changed, 17 insertions(+), 4 deletions(-)

diffs (56 lines):

diff -r 50e8ee585666 -r a3e5e5788e4e share/man/man9/localcount.9
--- a/share/man/man9/localcount.9       Mon Feb 25 20:47:37 2019 +0000
+++ b/share/man/man9/localcount.9       Mon Feb 25 21:43:00 2019 +0000
@@ -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 @@
 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 @@
 .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 @@
 .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