| LOCALCOUNT(9) | Kernel Developer's Manual | LOCALCOUNT(9) | 
localcount, localcount_init,
  localcount_fini,
  localcount_acquire,
  localcount_release,
  localcount_drain —
#include <sys/localcount.h>
void
  
  localcount_init(struct
    localcount *lc);
void
  
  localcount_fini(struct
    localcount *lc);
void
  
  localcount_acquire(struct
    localcount *lc);
void
  
  localcount_release(struct
    localcount *lc, struct
    kcondvar *cv, struct
    kmutex *mtx);
void
  
  localcount_drain(struct
    localcount *lc, struct
    kcondvar *cv, struct
    kmutex *mtx);
localcount references can be held across sleeps and
  can migrate between CPUs. Draining a localcount
  requires more expensive interprocessor synchronization than
  atomic_ops(3) (similar to
  psref(9)). And
  localcount references require eight bytes of memory
  per object per-CPU, significantly more than
  atomic_ops(3) and almost
  always more than psref(9).
As a rough heuristic, localcount should be
    used for classes of objects of which there are perhaps a few dozen instances
    (such as 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
    xyzioctl(IOC_READ_A_CPU_REG).
localcount_init(lc)No other operations can be performed on a localcount until it has been initialized.
localcount_fini(lc)localcount_drain(). The
      localcount may not be used after localcount_fini()
      has been called until it has been re-initialized by
      localcount_init().localcount_acquire(lc)The caller must ensure by some other mechanism that the
        localcount will not be destroyed before the call to
        localcount_acquire(); typically this will be via
        a pserialize(9) read
        section.
localcount_release(lc,
    cv, mtx)localcount_release() will broadcast availability
      of the condvar cv.localcount_drain(lc,
    cv, mtx)localcount_release().
    The caller must guarantee that no new references can be
        acquired with localcount_acquire() before
        calling localcount_drain(). For example, any
        object that may be found in a list and acquired must be removed from the
        list before calling localcount_drain(); removal
        from the list would typically be protected by calling
        pserialize_perform(9)
        to wait for any
        pserialize(9) readers
        to complete.
Once the localcount object lc is passed
        to localcount_drain(), it must be passed to
        localcount_fini() before any other re-use.
The header file sys/sys/localcount.h describes the public interface, and interfaces that machine-dependent code must provide to support localcounts.
localcount was designed by Taylor R.
  Campbell, who also provided a draft implementation. The implementation
  was completed, tested, and integrated by Paul Goyette.
localcount facility does not provide any way to
  examine the reference count without actually waiting for the count to reach
  zero.
Waiting for a localcount reference count
    to drain (reach zero) is a one-shot operation. Once the
    localcount has been drained, no further operations
    are allowed until the localcount has been
    re-initialized.
| February 25, 2019 | NetBSD 9.4 |