REFCNT_INIT(9) | 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 trace);

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`(const struct refcnt *r);

unsigned int
`refcnt_read`(const 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.

August 5, 2025 | Debian