SMR_CALL(9)

💅 SMR_CALL(9) — safe memory reclamation, but make it make sense

okay so bestie, welcome to SMR_CALL(9), a page straight outta the Kernel Developer's Manual and honestly? it's giving "locking is hard, let's not." this is the safe memory reclamation API and it's lowkey iconic once you get the vibe. let's go 🫶

---

✨ NAME ✨

smr_read_enter, smr_read_leave, smr_init, smr_call, smr_barrier, smr_flush, SMR_ASSERT_CRITICAL, SMR_ASSERT_NONCRITICAL — safe memory reclamation. that's the whole squad 💖

---

🌸 SYNOPSIS 🌸

#include <sys/smr.h>

void
smr_read_enter();

void
smr_read_leave();

void
smr_init(struct smr_entry *smr);

void
smr_call(struct smr_entry *smr, void (*fn)(void *), void *arg);

void
smr_barrier();

void
smr_flush();

void
SMR_ASSERT_CRITICAL();

void
SMR_ASSERT_NONCRITICAL();

---

🦋 DESCRIPTION 🦋

The safe memory reclamation API is literally the mechanism for reclaiming shared objects that readers can access without locking. no lock, no drama. objects that get reclaimed through SMR are called SMR-protected ✨

the mechanism guarantees that SMR-protected objects are not destroyed while readers are using them. like, they're protected protected. but — and this is the important part — it does not control how these objects are modified. that part is on you, bestie 💅

Readers access SMR-protected objects inside an SMR read-side critical section using SMR_PTR_GET(9). the section is entered with smr_read_enter(), and exited with smr_read_leave(). these routines never block. and sleeping? not allowed within an SMR read-side critical section. periodt. 😴🚫

smr_init() initializes the entry smr for use with smr_call().

smr_call() schedules a callback to be invoked after the entry smr cannot be referenced by a reader in an SMR read-side critical section. on invocation, the system calls function fn with argument arg in process context without any locks held. and get this — the implementation may delay the call in order to reduce overall system overhead by amortization. efficiency slay 🔥

smr_barrier() sleeps until any SMR read-side critical sections that are active on other CPUs at the time of invocation have ended. like with smr_call(), the processing of the request may be delayed. it's patient, it's chill, it's napping 💤

smr_flush() is like smr_barrier() but the system is forced to process the request as soon as possible. the use of this function is discouraged because of the heavy impact on system performance. so yeah, it works, but it's giving "main character energy at the cost of everyone else" 💀

🚨 To avoid deadlocks, the caller of smr_barrier() or smr_flush() must not hold locks that can block the processing of SMR callbacks. not a suggestion. actual rule. do not do it.

The SMR implementation does not limit the number of deferred calls. it is important to prevent arbitrary call rate of smr_call(). otherwise, it might be possible to exhaust system resources if the system is not able to invoke callbacks quickly enough. so like, please pace yourself 🙈

SMR_ASSERT_CRITICAL() and SMR_ASSERT_NONCRITICAL() can be used to assert that the current CPU is or is not in an SMR read-side critical section. vibe check, but for CPUs ⭐

---

🎀 CONTEXT 🎀

smr_read_enter(), smr_read_leave(), smr_call() and smr_init() can be called during autoconf, from process context, or from interrupt context. flexible icon behavior 👑

smr_barrier() and smr_flush() can be called from process context. just those two. know your place bestie 💅

---

🌈 SEE ALSO 🌈

• mutex(9)
• rwlock(9)
• SMR_LIST_INIT(9)
• SMR_PTR_GET(9)

go read them, iykyk 📚

---

💜 HISTORY 💜

The SMR API first appeared in OpenBSD 6.5. a classic. we stan an origin story 🍓

---

and that's the page, bestie!! tysm for reading 🧚 this little writeup comes to you from the Debian edition, dated June 22, 2022 — mwah, go forth and reclaim memory safely 💖✨