io_uring_buf_ring_add(3)

💖 io_uring_buf_ring_add(3) 💖

okay bestie, so this one lives in the liburing Manual and it's literally the glow-up your buffer ring has been waiting for ✨

🌸 NAME 🌸

io_uring_buf_ring_add — add buffers to a shared buffer ring 🎀

🦋 SYNOPSIS 🦋

#include <liburing.h>

void io_uring_buf_ring_add(struct io_uring_buf_ring *br,
                           void *addr,
                           unsigned int len,
                           unsigned short bid,
                           int mask,
                           int buf_offset);

✨ DESCRIPTION ✨

so io_uring_buf_ring_add(3) does the thing where it slides a brand new buffer into the shared buffer ring br. it's giving adding to the roster, no cap 💅

the buffer's address is addr, and it's len bytes long. simple as that.

• bid — this is the buffer ID, and bestie, it's coming back to you in the CQE. remember it. own it. 👑
• mask — the size mask of the ring, which you get from io_uring_buf_ring_mask(3).
• buf_offset — the offset to insert at from the current tail.

now here's the part where people get it wrong, so listen up 🫶 if you're adding just one buffer before committing the ring tail with io_uring_buf_ring_advance(3) or io_uring_buf_ring_cq_advance(3), then buf_offset should be 0. periodt. but if you're adding buffers in a loop before committing them, then buf_offset must be incremented by one for every single buffer you add. not two. not zero. one. increment it. don't skip. 🙈

💀 RETURN VALUE 💀

None. it literally returns nothing. it's a void. that's it, that's the whole section 🍓

🔥 NOTES 🔥

ngl this is the part that makes everything click: liburing (and the kernel, for that matter) does not care about what buffer ID maps to what buffer. like, zero opinions. none. 💀

and when you're recycling buffers after use? the application is totally free to add a different buffer into the same buffer ID location. iconic behavior, honestly. all that matters is that the application knows what a given buffer ID corresponds to in time in terms of virtual memory. that's the whole vibe check.

there's no liburing or kernel assumption that these mappings are persistent over time. they can very well be different every single time a given buffer ID is added to the provided buffer ring. so don't get attached. it's not that kind of relationship 💔✨

🌈 SEE ALSO 🌈

• io_uring_register_buf_ring(3)
• io_uring_buf_ring_mask(3)
• io_uring_buf_ring_advance(3)
• io_uring_buf_ring_cq_advance(3)

and that's the whole page, bestie!! this one's from liburing-2.2, dated May 18, 2022 — go forth and add those buffers, increment that buf_offset, and slay 💅💖✨🦋