REFCNT_INIT(9)

💖 REFCNT_INIT(9) 💖

okay bestie, welcome to the REFCNT_INIT(9) page from the Kernel Developer's Manual ✨ this one is literally all about the reference count API and it's giving “keep my shared object alive” energy 🫶

---

✨ 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. no cap, that's the whole vibe: count your refs so your object doesn't get deleted while somebody still needs it 😭

• refcnt_init() — sets the initial value of the counter to 1 to account for the caller's reference to the object. starting fresh, main character energy 👑
• refcnt_init_trace() — does the same thing, but additionally accepts a dt(4) static probe index. fancy ✨
• refcnt_take() — used to acquire a new reference. bestie, it is the responsibility of the caller to guarantee that it holds a valid reference before taking a new reference. don't skip that part, fr fr 🫶
• refcnt_rele() — used to release an existing reference. bye, reference 💅
• refcnt_rele_wake() — 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. wakey wakey 🌈
• 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. so like… one finalize caller only, okay? 👀
• refcnt_shared() — tests if the object has multiple references. is it shared? vibe check 🔥
• refcnt_read() — returns a snapshot of the counter value. its use is discouraged, and code should use refcnt_shared() whenever possible. lowkey don't reach for this one unless you gotta 🙈
• REFCNT_INITIALIZER() — initialises a declaration of a refcnt to 1. cute little declaration starter 🎀

okay and the memory-ordering part is important, so listen up: 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. literally the whole “don't touch it after it's gone” situation 💀

---

💜 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. versatile icons ✨

refcnt_finalize() can be called from process context. that's the one with the sleepy-wait energy 😴

---

💅 RETURN VALUES 💅

• refcnt_rele() — returns a non-zero value if the last reference has been released, otherwise 0. last one out? non-zero, bestie 🎉
• refcnt_shared() — returns a non-zero value if the object has multiple references, otherwise 0. multiple refs = non-zero, no cap 💖
• refcnt_read() — returns a snapshot of the counter value. just a lil snapshot 📸

---

mwah 💋 this cutie came from Debian on August 5, 2025, and it's literally REFCNT_INIT(9) — periodt 🦋