REFCOUNT(9)

💖 REFCOUNT(9) 💖

okay bestie, we're in the Kernel Developer's Manual today and we are talking about refcount — yes, the whole lil family: refcount_init, refcount_acquire, refcount_release. they manage a simple reference counter. that's it. that's the vibe. 👑

✨ NAME ✨

refcount, refcount_init, refcount_acquire, refcount_release — manage a simple reference counter 🎀

🌸 SYNOPSIS 🌸

like, here's the receipts:

#include <sys/param.h>
#include <sys/refcount.h>

void
refcount_init(volatile u_int *count, u_int value);

void
refcount_acquire(volatile u_int *count);

bool
refcount_release(volatile u_int *count);

🦋 DESCRIPTION 🦋

so the refcount functions are literally just an API to manage a simple reference counter. that's the whole job. 💅

the caller provides the storage for the counter in an unsigned integer. a pointer to this integer gets passed in via count. usually the counter is used to manage the lifetime of an object and it's stored as a member of the object. classic. icon behaviour. ✨

refcount_init() sets the initial value of the counter to value. it's normally used when you're creating a reference-counted object. brand new object, brand new counter, we love a fresh start 🫶

refcount_acquire() is how you acquire a new reference. now listen — the caller is responsible for making sure it holds a valid reference while obtaining a new reference. for example, if an object is stored on a list and the list holds a reference on the object, then holding a lock that protects the list gives you sufficient protection for acquiring a new reference. iykyk. 🔒

refcount_release() releases an existing reference. it returns true if the reference being released was the last reference; otherwise it returns false. no cap. 💀

⚠️ note bestie, and this part is IMPORTANT: these routines do not provide any inter-CPU synchronization, data protection, or memory ordering guarantees — except for managing the counter. that's literally it. the caller is responsible for any additional synchronization needed by consumers of any containing objects. AND the caller is also responsible for managing the life cycle of any containing objects, including explicitly releasing any resources when the last reference is released. do not forget that part fr fr 😭

🎀 RETURN VALUES 🎀

the refcount_release function returns true when releasing the last reference and false when releasing any other reference. simple. slay. ⭐

💜 HISTORY 💜

these functions were introduced in FreeBSD 6.0. throwback era, we respect the elders 🙈

and that's the whole page bestie!! this little cutie came to you from the Debian build, dated July 21, 2019 — yeah she's a lil vintage but she still ate 💅✨ go forth and count your references responsibly, mwah 🫶💖