.\"	$NetBSD: localcount.9,v 1.7 2019/02/25 21:43:00 pgoyette Exp $
.\"
.\" Copyright (c) 2016 The NetBSD Foundation
.\" 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 February 25, 2019
.Dt LOCALCOUNT 9
.Os
.Sh NAME
.Nm localcount ,
.Nm localcount_init ,
.Nm localcount_fini ,
.Nm localcount_acquire ,
.Nm localcount_release ,
.Nm localcount_drain
.Nd reference-count primitives
.Sh SYNOPSIS
.In sys/localcount.h
.Ft void
.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"
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"
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"
Acquire a reference to the localcount
.Ar lc .
.Pp
The caller must ensure by some other mechanism that the localcount will
not be destroyed before the call to
.Fn localcount_acquire ;
typically this will be via a
.Xr pserialize 9
read section.
.It Fn localcount_release "lc" "cv" "mtx"
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"
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
.Fn 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 ;
removal from the list would typically be protected by calling
.Xr pserialize_perform 9
to wait for any
.Xr pserialize 9
readers to complete.
.Pp
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.
.El
.Sh CODE REFERENCES
The core of the localcount implementation is located 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 ,
.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 drain (reach zero) is a one-shot operation.
Once the
.Nm
has been drained, no further operations are allowed until the
.Nm
has been re-initialized.