[src/trunk]: src/share/man/man9 Add locking(9) and psref(9) summaries to lock...

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

details:   https://anonhg.NetBSD.org/src/rev/94ae741404ff
branches:  trunk
changeset: 826253:94ae741404ff
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Wed Aug 23 22:27:55 2017 +0000

description:
Add locking(9) and psref(9) summaries to locking(9).

PR misc/52504

XXX Pull-up to -8 ?

diffstat:

 share/man/man9/locking.9 |  34 +++++++++++++++++++++++++++++++++-
 1 files changed, 33 insertions(+), 1 deletions(-)

diffs (55 lines):

diff -r 629e66b12a18 -r 94ae741404ff share/man/man9/locking.9
--- a/share/man/man9/locking.9  Wed Aug 23 21:18:57 2017 +0000
+++ b/share/man/man9/locking.9  Wed Aug 23 22:27:55 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: locking.9,v 1.5 2017/04/16 07:05:24 wiz Exp $
+.\"    $NetBSD: locking.9,v 1.6 2017/08/23 22:27:55 pgoyette Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -212,6 +212,36 @@
 .Pp
 See
 .Xr pserialize 9 .
+.Ss Passive reference mechanism
+Passive references allow CPUs to cheaply acquire and release passive
+references to a resource, which guarantee the resource will not be
+destroyed until the reference is released.  Acquiring and releasing
+passive references requires no interprocessor synchronization, except
+when the resource is pending destruction.
+.Pp
+See
+.Xr psref 9 .
+.Ss Localcount mechanism
+Localcounts are used in the kernel to implement a medium-weight reference
+counting mechanism.  During normal operations, localcounts do not need
+the interprocessor synchronization associated with
+.Xr atomic_ops 3
+atomic memory operations, and (unlike
+.Xr psref 9 )
+localcount references can be held across sleeps and can migrate between
+CPUs.  Draining a localcount requires more expensive interprocessor
+synchronization than
+.Xr atomic_ops 3
+(similar to
+.Xr psref 9 ) .
+And localcount references require eight bytes of memory per object per-CPU,
+significantly more than
+.Xr atomic_ops 3
+and almost always more than
+.Xr psref 9 .
+.Pp
+See
+.Xr localcount 9 .
 .Ss Simple do-it-in-thread-context framework
 The workqueue utility routines are provided to defer work which is needed to be
 processed in a thread context.
@@ -236,6 +266,8 @@
 .It Xr spl 9 Ta yes Ta no Ta no
 .It Xr splraiseipl 9 Ta yes Ta no Ta no
 .It Xr pserialize 9 Ta yes Ta yes Ta no
+.It Xr psref 9 Ta yes Ta yes Ta no
+.It Xr localcount 9 Ta yes Ta yes Ta no
 .It Xr workqueue 9 Ta yes Ta yes Ta yes
 .El
 .Sh SEE ALSO