BUF_RING(9)

💖 BUF_RING(9) — the lock-less ring buffer that could 💖

okay so bestie, listen up, because we're about to get into buf_ring(9) from the FreeBSD Kernel Developer's Manual and honestly? she's iconic. this whole page is about a multi-producer, {single, multi}-consumer lock-less ring buffer, and it's giving main character energy in the kernel. no cap, let's go. 🎀

---

✨ NAME ✨

so the squad here is: buf_ring, buf_ring_alloc, buf_ring_free, buf_ring_enqueue, buf_ring_dequeue_mc, buf_ring_dequeue_sc, buf_ring_count, buf_ring_empty, buf_ring_full, and buf_ring_peek. they all team up to bring you a multi-producer, {single, multi}-consumer lock-less ring buffer. periodt. 💅

---

🌸 SYNOPSIS 🌸

here's the vibe code-wise, bestie. copy it exactly, no edits:

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

struct buf_ring *
buf_ring_alloc(int count, struct malloc_type *type, int flags,
    struct mtx *sc_lock);

void
buf_ring_free(struct buf_ring *br, struct malloc_type *type);

int
buf_ring_enqueue(struct buf_ring *br, void *buf);

void *
buf_ring_dequeue_mc(struct buf_ring *br);

void *
buf_ring_dequeue_sc(struct buf_ring *br);

int
buf_ring_count(struct buf_ring *br);

int
buf_ring_empty(struct buf_ring *br);

int
buf_ring_full(struct buf_ring *br);

void *
buf_ring_peek(struct buf_ring *br);

---

🦋 DESCRIPTION 🦋

so the buf_ring functions serve up a lock-less multi-producer and lock-less multi-consumer as well as single-consumer ring buffer. that's the whole vibe. ✨

here's the breakdown, one by one, because we don't skip:

• buf_ring_alloc() — this one allocates a buf_ring ring buffer with count slots, using the malloc type type and memory flags flags. and plot twist: the single consumer interface is protected by sc_lock. 🔒
• buf_ring_free() — frees a buf_ring. ⚠️ but bestie, listen: the user is responsible for freeing any enqueued items. don't just free the ring and ghost the contents, that's not cute. 😭
• buf_ring_enqueue() — enqueues a buffer onto a buf_ring. simple as that, slay. 💖
• buf_ring_dequeue_mc() — the multi-consumer safe way to dequeue elements from a buf_ring. safe for the whole group chat, no drama. 🫶
• buf_ring_dequeue_sc() — the single-consumer interface to dequeue elements, and this one requires the user to serialize accesses with a lock. no cap, you gotta lock it yourself. 🔐
• buf_ring_count() — returns the number of elements in a buf_ring. the headcount, basically. 🔢
• buf_ring_empty() — returns TRUE if the buf_ring is empty, FALSE otherwise. is the party over? check here. 🎈
• buf_ring_full() — returns TRUE if no more items can be enqueued, FALSE otherwise. the velvet rope is up, bestie. 🚫
• buf_ring_peek() — returns a pointer to the last element in the buf_ring if the buf_ring is not empty, and NULL otherwise. just a lil look, no dequeue. 👀

---

🌈 RETURN VALUES 🌈

buf_ring_enqueue() returns ENOBUFS if there are no available slots in the buf_ring. that's it, that's the tea. ☕

---

👑 HISTORY 👑

these functions were introduced in FreeBSD 8.0. a classic, an icon, a legend. ⭐

---

okay bestie, that's the whole page. stay lock-less, stay iconic, and remember — always free your enqueued items. 💜

<div align="right">— with love from the Debian fam, dated September 27, 2012, signing off as BUF_RING(9) 🎀✨</div>