REFCNT_INIT(9)

NAME
refcnt_init, 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_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_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 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_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.