*** UNIX MANUAL PAGE BROWSER ***

REFCNT_INIT(9) FreeBSD Kernel Developer's Manual REFCNT_INIT(9) NAME refcnt_init, refcnt_init_trace, refcnt_take, refcnt_rele, refcnt_rele_wake, refcnt_finalize, refcnt_shared, refcnt_read, REFCNT_INITIALIZER - reference count API SYNOPSIS #include <sys/refcnt.h> void refcnt_init(struct refcnt *r); void refcnt_init_trace(struct refcnt *r, int idx); void refcnt_take(struct refcnt *r); int refcnt_rele(struct refcnt *r); void refcnt_rele_wake(struct refcnt *r); void refcnt_finalize(struct refcnt *r, const char *wmesg); int refcnt_shared(struct refcnt *r); unsigned int refcnt_read(struct refcnt *r); REFCNT_INITIALIZER(); DESCRIPTION The refcnt API provides simple reference counters that can be used to manage the lifetime of a shared object. refcnt_init() sets the initial value of the counter to 1 to account for the caller's reference to the object. refcnt_init_trace() additionally accepts a dt(4) static probe index. refcnt_take() is used to acquire a new reference. It is the responsibility of the caller to guarantee that it holds a valid reference before taking a new reference. refcnt_rele() is used to release an existing reference. refcnt_rele_wake() is used to release an existing reference and wakes up a process that is currently waiting in refcnt_finalize() for all the references to be released. refcnt_finalize() releases the caller's reference and sleeps until all the other references to the relevant object have been released. There may only be one caller to refcnt_finalize() per refcnt r. refcnt_rele(), refcnt_rele_wake() and refcnt_finalize() order prior memory loads and stores before the release of the reference. The functions enforce control dependency so that after the final reference has been released, subsequent loads and stores happen after the release. These ensure that concurrent accesses cease before the object's destructor runs and that the destructor sees all updates done during the lifetime of the object. refcnt_shared() tests if the object has multiple references. refcnt_read() returns a snapshot of the counter value. Its use is discouraged, code should use refcnt_shared() whenever possible. REFCNT_INITIALIZER() initialises a declaration of a refcnt to 1. CONTEXT refcnt_init(), refcnt_init_trace(), refcnt_take(), refcnt_rele(), refcnt_rele_wake(), refcnt_shared() and refcnt_read() can be called during autoconf, from process context, or from interrupt context. refcnt_finalize() can be called from process context. RETURN VALUES refcnt_rele() returns a non-zero value if the last reference has been released, otherwise 0. refcnt_shared() returns a non-zero value if the object has multiple references, otherwise 0. refcnt_read() returns a snapshot of the counter value. FreeBSD 14.1-RELEASE-p8 July 12, 2023 FreeBSD 14.1-RELEASE-p8