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 n 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 .
p 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 l -tag -width abcd t Fn localcount_init "lc" Dynamically initialize localcount .Ar lc for use.
p No other operations can be performed on a localcount until it has been initialized. t 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 . t Fn localcount_acquire "lc" Acquire a reference to the localcount .Ar lc .
p 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. t 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 . t 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 .
p 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.
p 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
a sys/kern/subr_localcount.c .
p The header file
a 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.
p 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.
Indexes created Tue Sep 23 23:09:58 GMT 2025