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_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.