[src/trunk]: src Add pserialize(9) manual page.

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

details:   https://anonhg.NetBSD.org/src/rev/d82bc653cfce
branches:  trunk
changeset: 767790:d82bc653cfce
user:      rmind <rmind%NetBSD.org@localhost>
date:      Sat Jul 30 18:19:04 2011 +0000

description:
Add pserialize(9) manual page.

diffstat:

 distrib/sets/lists/comp/mi  |    5 +-
 share/man/man9/Makefile     |    9 ++-
 share/man/man9/pserialize.9 |  110 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+), 3 deletions(-)

diffs (177 lines):

diff -r 1f2b0bdcffe7 -r d82bc653cfce distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sat Jul 30 17:01:04 2011 +0000
+++ b/distrib/sets/lists/comp/mi        Sat Jul 30 18:19:04 2011 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1649 2011/07/28 22:32:28 joerg Exp $
+#      $NetBSD: mi,v 1.1650 2011/07/30 18:19:04 rmind Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -10249,6 +10249,7 @@
 ./usr/share/man/cat9/propdb_create.0           comp-obsolete           obsolete
 ./usr/share/man/cat9/propdb_destroy.0          comp-obsolete           obsolete
 ./usr/share/man/cat9/properties.0              comp-obsolete           obsolete
+./usr/share/man/cat9/pserialize.0              comp-sys-catman         .cat
 ./usr/share/man/cat9/psignal.0                 comp-sys-catman         .cat
 ./usr/share/man/cat9/putiobuf.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/putter.0                  comp-sys-catman         .cat
@@ -16210,6 +16211,7 @@
 ./usr/share/man/html9/prop_copyin_ioctl.html   comp-sys-htmlman        html
 ./usr/share/man/html9/prop_dictionary_copyin_ioctl.html        comp-sys-htmlman        html
 ./usr/share/man/html9/prop_dictionary_copyout_ioctl.html       comp-sys-htmlman        html
+./usr/share/man/html9/pserialize.html          comp-sys-htmlman        html
 ./usr/share/man/html9/psignal.html             comp-sys-htmlman        html
 ./usr/share/man/html9/putiobuf.html            comp-sys-htmlman        html
 ./usr/share/man/html9/putter.html              comp-sys-htmlman        html
@@ -22355,6 +22357,7 @@
 ./usr/share/man/man9/propdb_create.9           comp-obsolete           obsolete
 ./usr/share/man/man9/propdb_destroy.9          comp-obsolete           obsolete
 ./usr/share/man/man9/properties.9              comp-obsolete           obsolete
+./usr/share/man/man9/pserialize.9              comp-sys-man            .man
 ./usr/share/man/man9/psignal.9                 comp-sys-man            .man
 ./usr/share/man/man9/putiobuf.9                        comp-sys-man            .man
 ./usr/share/man/man9/putter.9                  comp-sys-man            .man
diff -r 1f2b0bdcffe7 -r d82bc653cfce share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sat Jul 30 17:01:04 2011 +0000
+++ b/share/man/man9/Makefile   Sat Jul 30 18:19:04 2011 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.348 2011/06/03 18:43:38 rmind Exp $
+#       $NetBSD: Makefile,v 1.349 2011/07/30 18:19:05 rmind Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -40,7 +40,7 @@
        panic.9 pathbuf.9 pci.9 pci_configure_bus.9 pci_intr.9 pckbport.9 \
        pcmcia.9 pcq.9 percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 \
        pmc.9 pmf.9 pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \
-       preempt.9 proc_find.9 putter.9 \
+       preempt.9 proc_find.9 pserialize.9 putter.9 \
        radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 roundup.9 \
        rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \
        sched_4bsd.9 sched_m2.9 scsipi.9 \
@@ -609,6 +609,11 @@
        pool_cache.9 pool_cache_invalidate.9
 MLINKS+=powerhook_establish.9 powerhook_disestablish.9
 MLINKS+=preempt.9 yield.9
+MLINKS+=pserialize.9 pserialize_create.9 \
+       pserialize.9 pserialize_destroy.9 \
+       pserialize.9 pserialize_read_enter.9 \
+       pserialize.9 pserialize_read_exit.9 \
+       pserialize.9 pserialize_perform.9
 MLINKS+=ras.9 ras_lookup.9 \
        ras.9 ras_fork.9 \
        ras.9 ras_purgeall.9
diff -r 1f2b0bdcffe7 -r d82bc653cfce share/man/man9/pserialize.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pserialize.9       Sat Jul 30 18:19:04 2011 +0000
@@ -0,0 +1,110 @@
+.\"    $NetBSD: pserialize.9,v 1.1 2011/07/30 18:19:05 rmind Exp $
+.\"
+.\" Copyright (c) 2011 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd July 30, 2011
+.Dt PSERIALIZE 9
+.Os
+.Sh NAME
+.Nm pserialize
+.Nd passive serialization mechanism
+.Sh SYNOPSIS
+.In sys/pserialize.h
+.Ft pserialize_t
+.Fn pserialize_create "void"
+.Ft void
+.Fn pserialize_destroy "pserialize_t psz"
+.Ft int
+.Fn pserialize_read_enter "void"
+.Ft void
+.Fn pserialize_read_exit "int s"
+.Ft void
+.Fn pserialize_perform "pserialize_t psz"
+.\" -----
+.Sh DESCRIPTION
+Passive serialization is a reader / writer synchronisation mechanism
+designed for lock-less read operations.
+The read operations may happen from software interrupt at
+.Dv IPL_SOFTCLOCK .
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn pserialize_create
+Allocate a new synchronisation object.
+.It Fn pserialize_destroy
+Destroy the synchronisation object.
+No synchronisation activity should happen at this point.
+.It Fn pserialize_read_enter
+Enter the critical path of the reader side.
+Returns an IPL value, which must be passed to
+.Xr pserialize_read_exit 9 .
+Protected code path is not allowed to block.
+.It Fn pserialize_read_exit
+Exit the critical path of the reader side.
+Takes the IPL value returned by
+.Xr pserialize_read_enter 9 .
+.It Fn pserialize_perform
+Perform the passive serialization on the writer side.
+Passing of this function ensures that no readers are in action.
+Writers must be additionally serialized with a separate mechanism,
+e.g.
+.Xr mutex 9 .
+Operation blocks and it may only be performed from thread context.
+.El
+.\" -----
+.Sh EXAMPLES
+Typical code fragment in the writer side:
+.Bd -literal
+       mutex_enter(\*[Am]writer_psz_lock);
+       /*
+        * Perform the updates (e.g. remove data items from a list).
+        */
+       ...
+       pserialize_perform(object-\*[Gt]psz);
+       /*
+        * At this point it is safe to destroy old data items.
+        */
+       mutex_exit(\*[Am]writer_psz_lock);
+.Ed
+.\" -----
+.Sh CODE REFERENCES
+The
+.Nm
+is implemented within the file
+.Pa sys/kern/subr_pserialize.c .
+.Sh SEE ALSO
+.Xr condvar 9 ,
+.Xr membar 9 ,
+.Xr mutex 9 ,
+.Xr rwlock 9
+.Rs
+.%A Hennessy, et al.
+.%T "Passive serialization in a multitasking environment "
+.%I US Patent and Trademark Office
+.%D February 28, 1989 
+.%N US Patent 4809168
+.Re
+.Sh HISTORY
+Passive serialization mechanism first appeared in
+.Nx 6.0 .