Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add passive references, intermediate between pserialize and ...
details: https://anonhg.NetBSD.org/src/rev/7b9d75e10f59
branches: trunk
changeset: 344628:7b9d75e10f59
user: riastradh <riastradh%NetBSD.org@localhost>
date: Sat Apr 09 06:21:16 2016 +0000
description:
Add passive references, intermediate between pserialize and refcount.
Discussed on tech-kern:
https://mail-index.netbsd.org/tech-kern/2016/01/24/msg020069.html
API is still experimental and likely to change. (Obvious changes:
either remove extra arguments everywhere, or shrink psref_target to a
single bit, at the expense of possibly valuable diagnostic checks.)
Should do some real testing before we use this in anger!
diffstat:
distrib/sets/lists/comp/mi | 29 ++-
share/man/man9/Makefile | 12 +-
share/man/man9/pslist.9 | 5 +-
share/man/man9/psref.9 | 405 +++++++++++++++++++++++++++++++++++++
sys/kern/files.kern | 3 +-
sys/kern/subr_psref.c | 482 +++++++++++++++++++++++++++++++++++++++++++++
sys/sys/psref.h | 95 ++++++++
7 files changed, 1025 insertions(+), 6 deletions(-)
diffs (truncated from 1120 to 300 lines):
diff -r c56a7b87e0ca -r 7b9d75e10f59 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Sat Apr 09 05:16:23 2016 +0000
+++ b/distrib/sets/lists/comp/mi Sat Apr 09 06:21:16 2016 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2027 2016/04/09 04:39:46 riastradh Exp $
+# $NetBSD: mi,v 1.2028 2016/04/09 06:21:16 riastradh Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10688,6 +10688,15 @@
./usr/share/man/cat9/pserialize_read_exit.0 comp-sys-catman .cat
./usr/share/man/cat9/psignal.0 comp-sys-catman .cat
./usr/share/man/cat9/pslist.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_acquire.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_class_create.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_class_destroy.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_copy.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_held.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_release.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_target_destroy.0 comp-sys-catman .cat
+./usr/share/man/cat9/psref_target_init.0 comp-sys-catman .cat
./usr/share/man/cat9/ptoa.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
@@ -17728,6 +17737,15 @@
./usr/share/man/html9/pserialize_read_exit.html comp-sys-htmlman html
./usr/share/man/html9/psignal.html comp-sys-htmlman html
./usr/share/man/html9/pslist.html comp-sys-htmlman html
+./usr/share/man/html9/psref.html comp-sys-catman html
+./usr/share/man/html9/psref_acquire.html comp-sys-catman html
+./usr/share/man/html9/psref_class_create.html comp-sys-catman html
+./usr/share/man/html9/psref_class_destroy.html comp-sys-catman html
+./usr/share/man/html9/psref_copy.html comp-sys-catman html
+./usr/share/man/html9/psref_held.html comp-sys-catman html
+./usr/share/man/html9/psref_release.html comp-sys-catman html
+./usr/share/man/html9/psref_target_destroy.html comp-sys-catman html
+./usr/share/man/html9/psref_target_init.html comp-sys-catman html
./usr/share/man/html9/ptoa.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
@@ -24950,6 +24968,15 @@
./usr/share/man/man9/pserialize_read_exit.9 comp-sys-man .man
./usr/share/man/man9/psignal.9 comp-sys-man .man
./usr/share/man/man9/pslist.9 comp-sys-man .man
+./usr/share/man/man9/psref.9 comp-sys-man .man
+./usr/share/man/man9/psref_acquire.9 comp-sys-man .man
+./usr/share/man/man9/psref_class_create.9 comp-sys-man .man
+./usr/share/man/man9/psref_class_destroy.9 comp-sys-man .man
+./usr/share/man/man9/psref_copy.9 comp-sys-man .man
+./usr/share/man/man9/psref_held.9 comp-sys-man .man
+./usr/share/man/man9/psref_release.9 comp-sys-man .man
+./usr/share/man/man9/psref_target_destroy.9 comp-sys-man .man
+./usr/share/man/man9/psref_target_init.9 comp-sys-man .man
./usr/share/man/man9/ptoa.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 c56a7b87e0ca -r 7b9d75e10f59 share/man/man9/Makefile
--- a/share/man/man9/Makefile Sat Apr 09 05:16:23 2016 +0000
+++ b/share/man/man9/Makefile Sat Apr 09 06:21:16 2016 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.394 2016/04/09 04:39:46 riastradh Exp $
+# $NetBSD: Makefile,v 1.395 2016/04/09 06:21:16 riastradh Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -43,7 +43,7 @@
pci_msi.9 pckbport.9 pcmcia.9 pcq.9 pcu.9 \
percpu.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 pmf.9 pool.9 \
pool_cache.9 powerhook_establish.9 ppi.9 ppsratecheck.9 preempt.9 \
- proc_find.9 pserialize.9 pslist.9 putter.9 \
+ proc_find.9 pserialize.9 pslist.9 psref.9 putter.9 \
radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rndsink.9 \
roundup.9 rssadapt.9 rt_timer.9 rwlock.9 RUN_ONCE.9 STACK.9 \
scanc.9 \
@@ -721,6 +721,14 @@
pslist.9 PSLIST_WRITER_INSERT_HEAD.9 \
pslist.9 PSLIST_WRITER_NEXT.9 \
pslist.9 PSLIST_WRITER_REMOVE.9
+MLINKS+=psref.9 psref_acquire.9 \
+ psref.9 psref_class_create.9 \
+ psref.9 psref_class_destroy.9 \
+ psref.9 psref_copy.9 \
+ psref.9 psref_held.9 \
+ psref.9 psref_release.9 \
+ psref.9 psref_target_destroy.9 \
+ psref.9 psref_target_init.9
MLINKS+=ras.9 ras_lookup.9 \
ras.9 ras_fork.9 \
ras.9 ras_purgeall.9
diff -r c56a7b87e0ca -r 7b9d75e10f59 share/man/man9/pslist.9
--- a/share/man/man9/pslist.9 Sat Apr 09 05:16:23 2016 +0000
+++ b/share/man/man9/pslist.9 Sat Apr 09 06:21:16 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: pslist.9,v 1.2 2016/04/09 05:16:23 riastradh Exp $
+.\" $NetBSD: pslist.9,v 1.3 2016/04/09 06:21:16 riastradh Exp $
.\"
.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -420,7 +420,8 @@
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr queue 3 ,
-.Xr pserialize 9
+.Xr pserialize 9 ,
+.Xr psref 9
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh HISTORY
The
diff -r c56a7b87e0ca -r 7b9d75e10f59 share/man/man9/psref.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/psref.9 Sat Apr 09 06:21:16 2016 +0000
@@ -0,0 +1,405 @@
+.\" $NetBSD: psref.9,v 1.1 2016/04/09 06:21:16 riastradh Exp $
+.\"
+.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Taylor R. Campbell.
+.\"
+.\" 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 April 8, 2016
+.Dt PSREF 9
+.Os
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm psref
+.Nd passive references
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.In sys/psref.h
+.\"
+.Ft struct psref_class *
+.Fn psref_class_create "const char *name" "int ipl"
+.Ft void
+.Fn psref_class_destroy "struct psref_class *class"
+.\"
+.Ft void
+.Fn psref_target_init "struct psref_target *target" "struct psref_class *class"
+.Ft void
+.Fn psref_target_destroy "struct psref_target *target" "struct psref_class *class"
+.\"
+.Ft void
+.Fn psref_acquire "struct psref *ref" "const struct psref_target *target" "struct psref_class *class"
+.Ft void
+.Fn psref_release "struct psref *ref" "const struct psref_target *target" "struct psref_class *class"
+.Ft void
+.Fn psref_copy "struct psref *pto" "const struct psref *pfrom" "struct psref_class *class"
+.\"
+.Pp
+.Fd "#ifdef DIAGNOSTIC"
+.Ft bool
+.Fn psref_held "const struct psref_target *target" "struct psref_class *class"
+.Fd "#endif"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+The
+.Nm
+abstraction allows CPUs to cheaply acquire references to a resource,
+called
+.Em passive references ,
+guaranteeing it will not be destroyed until all CPUs release their
+references to it, without using interprocessor synchronization on the
+reader side.
+.\"
+.Pp
+Passive references are an intermediate between
+.Xr pserialize 9
+and reference counting:
+.Bl -hyphen
+.It
+.Xr pserialize 9
+read sections require no interprocessor synchronization, but must be
+of short duration, and may not sleep.
+A
+.Xr pserialize 9
+read section blocks soft interrupts on the local CPU until it is
+complete.
+.It
+Reference counting requires interprocessor synchronization via
+.Xr atomic_ops 9
+or
+.Xr mutex 9 .
+However, with reference counting, a reference may be held for arbitrary
+durations, may be transferred between owners across CPUs and threads,
+and may be held by a caller that sleeps.
+.El
+.\"
+.Pp
+Passive references share some properties of both: passive references
+require no interprocessor synchronization to acquire or release, and do
+not block soft interrupts, but can be held by a caller that sleeps.
+However, a caller holding a passive reference may not transfer it from
+one LWP to another, and the caller's LWP must be bound to a single CPU
+while it holds any passive references.
+.Pp
+Thus, passive references are useful for incrementally parallelizing
+resources whose operations may sleep, such as in the network stack,
+before comprehensively removing sleeps from the code paths involved.
+.\"
+.Pp
+Resources to which callers may hold passive references are called
+.Em targets ,
+and must contain an embedded
+.Vt struct psref_target
+object, initialized with
+.Fn psref_target_init .
+.Pp
+When a caller wants to guarantee that a resource will not be destroyed
+until it is done, it must allocate storage for a
+.Vt struct psref
+object, find the
+.Vt struct psref_target
+for the resource it seeks, and use
+.Fn psref_acquire
+to acquire a passive reference.
+When a caller is done with the resource, it must release the resource
+with
+.Fn psref_release .
+.Pp
+When a resource is about to go away, its passive reference target must
+be passed to
+.Fn psref_target_destroy
+to wait until all extant passive references are released; then the
+resource itself may be freed.
+.\"
+.Pp
+.Vt struct psref_target
+and
+.Vt struct psref
+objects must be allocated by the caller, but they should be treated as
+opaque and should not be inspected or copied.
+.\"
+.Pp
+Passive reference targets are grouped into
+.Em classes ,
+represented by an opaque
+.Vt struct psref_class
+object, e.g. the class of all network routes, or the class of all file
+systems mount points, which may be needed at different interrupt
+priority levels.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh FUNCTIONS
+.Bl -tag -width abcd
+.It Fn psref_class_create name ipl
+Create a passive reference class with the given name and interrupt
+priority level, and return an opaque pointer describing it.
+The name must be at most eight characters long, and will be shown in
+utilities such as
+.Xr ps 1
+for threads that are waiting to destroy passive reference targets.
+On failure, return
+.Dv NULL
+instead.
+.\""""""""""""""""
+.It Fn psref_class_destroy class
+Destroy a passive reference class created with
+.Fn psref_class_create .
+There must be no more passive references in this class.
+.\""""""""""""""""
+.It Fn psref_target_init target class
+Initialize a passive reference target in a
+.Vt struct psref_target
+object allocated by the caller in the given class.
+.Pp
+The caller must issue a
+.Xr membar_producer 3
+after calling
+.Fn psref_target_init
+and before publishing a pointer to the target so that other CPUs can
+see it, e.g. by inserting it into a
+.Xr pslist 9 .
+.\""""""""""""""""
+.It Fn psref_target_destroy target class
+Wait for all extant passive references to
+.Fa target
+on all CPUs to be released, and then destroy it.
+The passive reference target
+.Fa target
Home |
Main Index |
Thread Index |
Old Index