Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Introduce new localcount(9) reference-count primitives.
details: https://anonhg.NetBSD.org/src/rev/08ed25cc8dbb
branches: trunk
changeset: 824012:08ed25cc8dbb
user: pgoyette <pgoyette%NetBSD.org@localhost>
date: Fri May 19 00:01:33 2017 +0000
description:
Introduce new localcount(9) reference-count primitives.
diffstat:
distrib/sets/lists/comp/mi | 6 +-
doc/CHANGES | 3 +-
share/man/man9/localcount.9 | 192 +++++++++++++++++++++++++++++++++
sys/kern/files.kern | 3 +-
sys/kern/subr_localcount.c | 255 ++++++++++++++++++++++++++++++++++++++++++++
sys/sys/Makefile | 4 +-
sys/sys/localcount.h | 65 +++++++++++
sys/sys/param.h | 4 +-
8 files changed, 525 insertions(+), 7 deletions(-)
diffs (truncated from 632 to 300 lines):
diff -r f80cda2fb9a1 -r 08ed25cc8dbb distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Thu May 18 18:33:48 2017 +0000
+++ b/distrib/sets/lists/comp/mi Fri May 19 00:01:33 2017 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2132 2017/05/09 22:43:09 kamil Exp $
+# $NetBSD: mi,v 1.2133 2017/05/19 00:01:33 pgoyette Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -2873,6 +2873,7 @@
./usr/include/sys/ksyms.h comp-c-include
./usr/include/sys/ktrace.h comp-c-include
./usr/include/sys/lkm.h comp-obsolete obsolete
+./usr/include/sys/localcount.h comp-c-include
./usr/include/sys/localedef.h comp-c-include
./usr/include/sys/lock.h comp-c-include
./usr/include/sys/lockf.h comp-c-include
@@ -10745,6 +10746,7 @@
./usr/share/man/cat9/le64enc.0 comp-sys-catman .cat
./usr/share/man/cat9/le64toh.0 comp-sys-catman .cat
./usr/share/man/cat9/linedisc.0 comp-sys-catman .cat
+./usr/share/man/cat9/localcount.0 comp-sys-catman .cat
./usr/share/man/cat9/lock.0 comp-sys-catman .cat
./usr/share/man/cat9/locking.0 comp-sys-catman .cat
./usr/share/man/cat9/lockinit.0 comp-sys-catman .cat
@@ -18192,6 +18194,7 @@
./usr/share/man/html9/le64enc.html comp-sys-htmlman html
./usr/share/man/html9/le64toh.html comp-sys-htmlman html
./usr/share/man/html9/linedisc.html comp-sys-htmlman html
+./usr/share/man/html9/localcount.html comp-sys-htmlman html
./usr/share/man/html9/lock.html comp-sys-htmlman html
./usr/share/man/html9/locking.html comp-sys-htmlman html
./usr/share/man/html9/lockinit.html comp-sys-htmlman html
@@ -25793,6 +25796,7 @@
./usr/share/man/man9/le64enc.9 comp-sys-man .man
./usr/share/man/man9/le64toh.9 comp-sys-man .man
./usr/share/man/man9/linedisc.9 comp-sys-man .man
+./usr/share/man/man9/localcount.9 comp-sys-man .man
./usr/share/man/man9/lock.9 comp-sys-man .man
./usr/share/man/man9/locking.9 comp-sys-man .man
./usr/share/man/man9/lockinit.9 comp-sys-man .man
diff -r f80cda2fb9a1 -r 08ed25cc8dbb doc/CHANGES
--- a/doc/CHANGES Thu May 18 18:33:48 2017 +0000
+++ b/doc/CHANGES Fri May 19 00:01:33 2017 +0000
@@ -1,4 +1,4 @@
-# LIST OF CHANGES FROM LAST RELEASE: <$Revision: 1.2282 $>
+# LIST OF CHANGES FROM LAST RELEASE: <$Revision: 1.2283 $>
#
#
# [Note: This file does not mention every change made to the NetBSD source tree.
@@ -513,3 +513,4 @@
openpam(3): update to 20170430 (resedacea) [christos 20170506]
dhcpcd: Import dhcpcd 7.0.0-rc1 [roy 20170510]
vioscsi(4): Stability fixes [jdolecek 20170515]
+ localcount(9): Add localcount ref-count primitives [pgoyette 20170519]
diff -r f80cda2fb9a1 -r 08ed25cc8dbb share/man/man9/localcount.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/localcount.9 Fri May 19 00:01:33 2017 +0000
@@ -0,0 +1,192 @@
+.\" $NetBSD: localcount.9,v 1.2 2017/05/19 00:01:33 pgoyette Exp $
+.\"
+.\" Copyright (c) 2016
+.\" 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 December 8, 2016
+.Dt LOCALCOUNT 9
+.Os
+.Sh NAME
+.Nm localcount ,
+.Nm localcount_init ,
+.Nm localcount_fini ,
+.Nm localcount_acquire ,
+.Nm localcount_release ,
+.Nm localcount_drain
+.Sh SYNOPSIS
+.In sys/localcount.h
+.Ft int
+.Fn localcount_init "struct localcount *lc"
+.Ft void
+.Fn localcount_fini "struct localcount *lc"
+.Ft void
+.Fn localcount_acquire "struct localcount *lc"
+.Ft void
+.Fn localcount_release "struct localcount *lc" "struct kcondvar *cv" \
+"struct kmutex *mtx"
+.Ft void
+.Fn localcount_drain "struct localcount *lc" "struct kcondvar *cv" \
+"struct kmutex *mtx"
+.Sh DESCRIPTION
+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 )
+.Nm
+references can be held across sleeps and can migrate between CPUs.
+Draining a
+.Nm
+requires more expensive interprocessor synchronization than
+.Xr atomic_ops 3
+(similar to
+.Xr psref 9 ) .
+And
+.Nm
+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
+As a rough heuristic,
+.Nm
+should be used for classes of objects of which there are perhaps a few dozen
+instances (such as
+.Xr autoconf 9
+devices) but not thousands of instances (such as
+network flows) and on which there may be a mixture of long-term I/O waits,
+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 abcd
+.It Fn localcount_init "lc"
+.Pp
+Dynamically initialize localcount
+.Ar lc
+for use.
+.Pp
+No other operations can be performed on a localcount until it has been
+initialized.
+.It Fn localcount_fini "lc"
+.Pp
+Release resources used by localcount
+.Ar lc .
+The caller must have already called
+.Fn localcount_drain .
+The localcount may not be used after
+.Fn localcount_fini
+has been called until it has been re-initialized by
+.Fn localcount_init .
+.It Fn localcount_acquire "lc"
+.Pp
+Acquire a reference to the localcount
+.Ar lc .
+.It Fn localcount_release "lc" "cv" "mtx"
+.Pp
+Release a reference to the localcount
+.Ar lc .
+If the localcount is currently being drained, the mutex
+.Ar mtx
+will be used to synchronize updates to the global reference count (i.e.
+the total across all CPUs).
+If the reference count goes to zero,
+.Fn localcount_release
+will broadcast availability of the condvar
+.Ar cv .
+.It Fn localcount_drain "lc" "cv" "mtx"
+.Pp
+Wait for all references to the localcount
+.Ar lc
+to be released.
+The caller must hold the mutex
+.Ar mtx ;
+the mutex will be released during inter-CPU cross-calls (see
+.Xr xcall 9 ) and while waiting on the condvar
+.Ar cv .
+The same
+.Ar cv
+and
+.Ar mtx
+must be used with
+.Fn localcount_release .
+.Pp
+The caller must guarantee that no new references can be acquired with
+localcount_acquire before calling
+.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 .
+Once the localcount object
+.Ar lc
+is passed to
+.Fn localcount_drain ,
+it must be passed to
+.Fn localcount_fini
+before any other re-use.
+.Sh CODE REFERENCES
+The core of the localcount implementation is in
+.Pa sys/kern/subr_localcount.c .
+.Pp
+The header file
+.Pa sys/sys/localcount.h
+describes the public interface, and interfaces that machine-dependent
+code must provide to support localcounts.
+.Sh SEE ALSO
+.Xr atomic_ops 3 ,
+.Xr condvar 9 ,
+.Xr mutex 9 ,
+and
+.Xr psref 9
+.Sh HISTORY
+The localcount primitives first appeared in
+.Nx 8.0 .
+.Sh AUTHORS
+.Nm
+was designed by
+.An -nosplit
+.An Taylor R. Campbell ,
+who also provided a draft implementation.
+The implementation was completed, tested, and integrated by
+.An Paul Goyette .
+.Sh CAVEATS
+The
+.Nm
+facility does not provide any way to examine the reference count without
+actually waiting for the count to reach zero.
+.Pp
+Waiting for a
+.Nm
+reference count to reach zero is a one-shot operation.
+Once the
+.Nm
+has been waited for, no further operations are allowed until the
+.Nm
+has been re-initialized.
+
diff -r f80cda2fb9a1 -r 08ed25cc8dbb sys/kern/files.kern
--- a/sys/kern/files.kern Thu May 18 18:33:48 2017 +0000
+++ b/sys/kern/files.kern Fri May 19 00:01:33 2017 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: files.kern,v 1.14 2017/04/12 20:05:54 christos Exp $
+# $NetBSD: files.kern,v 1.15 2017/05/19 00:01:33 pgoyette Exp $
#
# kernel sources
@@ -121,6 +121,7 @@
file kern/subr_kmem.c kern
file kern/subr_kobj.c kern
file kern/subr_kobj_vfs.c kern
+file kern/subr_localcount.c kern
file kern/subr_lockdebug.c kern
file kern/subr_log.c kern
file kern/subr_lwp_specificdata.c kern
diff -r f80cda2fb9a1 -r 08ed25cc8dbb sys/kern/subr_localcount.c
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/kern/subr_localcount.c Fri May 19 00:01:33 2017 +0000
@@ -0,0 +1,255 @@
+/* $NetBSD: subr_localcount.c,v 1.2 2017/05/19 00:01:33 pgoyette 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
Home |
Main Index |
Thread Index |
Old Index