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