SRPL_RC_INIT(9)

💅 SRPL_RC_INIT — singly-linked shared reference pointer list ✨

okay so picture this: a man page, but make it a group chat. This lil cutie lives in section 9 of the Kernel Developer's Manual, and it's all about the SRPL family — srpl_rc_init, SRPL_HEAD, SRPL_ENTRY, SRPL_INIT, SRPL_FIRST, SRPL_NEXT, SRPL_FOLLOW, SRPL_FOREACH, SRPL_LEAVE, and SRPL_RC_INITIALIZER. It's giving "singly-linked shared reference pointer list" and honestly? iconic. 🎀

---

✨ SYNOPSIS ✨

#include <sys/srp.h>

struct srpl_rc;

void
srpl_rc_init(struct srpl_rc *rc, void (*ref)(void *, void *),
    void (*unref)(void *, void *), void *ctx);

SRPL_HEAD(HEADNAME, TYPE);

SRPL_ENTRY(TYPE);

void
SRPL_INIT(SRPL_HEAD *sl);

void *
SRPL_FIRST(struct srp_ref *sr, SRPL_HEAD *sl);

void *
SRPL_NEXT(struct srp_ref *sr, struct TYPE *listelm, FIELDNAME);

void *
SRPL_FOLLOW(struct srp_ref *sr, struct TYPE *listelm, FIELDNAME);

SRPL_FOREACH(VARNAME, struct srp_ref *sr, SRPL_HEAD *sl, FIELDNAME);

void
SRPL_LEAVE(struct srp_ref *sr);

SRPL_RC_INITIALIZER(void (*ref)(void *, void *),
    void (*unref)(void *, void *), void *ctx);

---

🦋 DESCRIPTION 🦋

The SRPL list macros build a linked list on top of shared reference pointers, and the whole point of that is concurrent traversal 🔥 — you can walk the list and touch the items on it at the same time, no cap.

SRP lists are a generic type, and they're represented by a SRPL_HEAD. Any element you insert has to be a structure that contains a SRPL_ENTRY field. Also — and this part is important, bestie — those elements must support reference counting too, because insertion and removal operations can cause items to be temporarily referenced by multiple SRPs within the list at the same time. It's a whole vibe where an element gets a little crowd of references around it for a sec. 💅

• srpl_rc_init() — initialises the SRP list refcounts rc structure so it can be used to manage the reference counts on elements in the list. When you insert or remove an element in an SRP list, the reference counts on elements within the list get incremented via calls to ref. As these references are released by the SRP infrastructure, the reference counts get decremented by calls to unref. And unref is also responsible for freeing the element when the reference count reaches 0 — so yes, it's doing double duty, main character energy fr. Both ref and unref get called with ctx as their first argument and a pointer to the element as their second argument.
• SRPL_INIT() — initialises the SRP list sl to an empty state. clean slate, fresh start, we love to see it ✨
• SRPL_FIRST() — accesses the first element in the SRP list sl and holds its reference via sr.
• SRPL_NEXT() — accesses the element in the SRP list after listelm and holds its reference via sr.
• SRPL_FOLLOW() — accesses the element in the SRP list after listelm and swaps the previous reference held via sr for the reference of the newly accessed item. cute little trade-off, no notes 🫶
• SRPL_FOREACH() — creates a loop for traversing the list. Every single call to SRPL_FOREACH() must have a corresponding call to SRPL_LEAVE() to release references to the list and its elements. no skipping, no ghosting your references 😭
• SRPL_LEAVE() — releases references to the list and its elements held by previous calls to SRPL_FIRST(), SRPL_NEXT(), SRPL_FOLLOW(), or SRPL_FOREACH().

And if you've got an srpl_rc declaration, you can initialise it with the SRPL_RC_INITIALIZER() macro. 🌸

---

🌈 CONTEXT 🌈

Where you're allowed to call these, iykyk.

SRPL_INIT(), SRPL_FIRST(), SRPL_NEXT(), SRPL_FOLLOW(), SRPL_FOREACH(), and SRPL_LEAVE() may be called during autoconf, from process context, or from interrupt context. very flexible, very demure 💖

srpl_rc_init() may be called during autoconf or from process context. (slightly stricter invite list, but she's still slay.)

---

⭐ RETURN VALUES ⭐

SRPL_FIRST(), SRPL_NEXT(), and SRPL_FOLLOW() return a pointer to elements in the SRP list, or NULL if there are no more elements. so if you get NULL, that's your sign the list said "that's all bestie" 👑

---

🎀 SEE ALSO 🎀

• SRPL_FIRST_LOCKED(9)

---

👑 HISTORY 👑

The srp API was originally written by Jonathan Matthew <jmatthew@openbsd.org> and David Gwynne <dlg@openbsd.org> — legends, honestly. The SRP list API first appeared in OpenBSD 5.9. 🧚

---

and that's the whole page, bestie! this cutie came from the Debian crew, dated November 21, 2016, and it's out here doing the most in SRPL_RC_INIT(9). go traverse something safely, and don't forget to SRPL_LEAVE() — periodt 💜🌸🦋