Module Name: src
Committed By: rmind
Date: Sat Jul 30 18:19:05 UTC 2011
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: pserialize.9
Log Message:
Add pserialize(9) manual page.
To generate a diff of this commit:
cvs rdiff -u -r1.1649 -r1.1650 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.348 -r1.349 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/pserialize.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1649 src/distrib/sets/lists/comp/mi:1.1650
--- src/distrib/sets/lists/comp/mi:1.1649 Thu Jul 28 22:32:28 2011
+++ src/distrib/sets/lists/comp/mi Sat Jul 30 18:19:04 2011
@@ -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
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.348 src/share/man/man9/Makefile:1.349
--- src/share/man/man9/Makefile:1.348 Fri Jun 3 18:43:38 2011
+++ src/share/man/man9/Makefile Sat Jul 30 18:19:05 2011
@@ -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
Added files:
Index: src/share/man/man9/pserialize.9
diff -u /dev/null src/share/man/man9/pserialize.9:1.1
--- /dev/null Sat Jul 30 18:19:05 2011
+++ src/share/man/man9/pserialize.9 Sat Jul 30 18:19:05 2011
@@ -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 .
