io_uring_buf_ring_available(3)

✨ io_uring_buf_ring_available — the "bestie how many buffers do I even have left" helper ✨

okay so this is io_uring_buf_ring_available(3), and it lives in the liburing manual, section 3. it's the little function you call when you're like "wait. how many of my provided ring buffer entries has the kernel NOT eaten yet" 💅 and honestly? iconic of it to exist.

🌸 NAME 🌸

io_uring_buf_ring_available</p> — returns the number of unconsumed provided ring buffer entries 🎀

✨ SYNOPSIS ✨

#include <liburing.h>

int io_uring_buf_ring_available(struct io_uring *ring,
                                struct io_uring_buf_ring *br,
                                unsigned short bgid);

like. three args. so chill. 🦋

💖 DESCRIPTION 💖

so the io_uring_buf_ring_available(3) helper returns the number of unconsumed entries — unconsumed by the kernel, bestie, that's the key part — in the br provided buffer group. that group belongs to the io_uring ring and it's identified by the buffer group ID bgid. 🫶

and here's the ✨plot twist✨: the head of the provided buffer ring is only visible to the kernel. so there is literally no other way for you to know how many unconsumed entries are chillin' in that provided buffer ring. none. this function goes and queries the kernel to get that number back for you. it's giving personal assistant energy, fr fr. 🌈

available since kernel 6.8 🧚 — so if you're on something older, this is not the vibe, sorry bestie 😭

💀 NOTES 💀

the number it hands back reflects the amount of unconsumed entries at the exact time it was queried. periodt.

and ngl, if there's inflight IO that might consume provided buffers from this buffer group, then the returned value is inherently racy. like, no cap, it's a snapshot, not a promise. 🙈

👑 RETURN VALUE 👑

• on success — returns the number of unconsumed entries, which may be 0 (yes, zero is a valid slay, it just means nothing's left) ✨
• on error — it may return:
  • -ENOENT — if the specified buffer group doesn't exist 💀
  • -EINVAL — if the buffer group isn't of the correct type, or if the kernel doesn't support this feature 😭

🌟 SEE ALSO 🌟

• io_uring_register_buf_ring(3)
• io_uring_buf_ring_add(3)
• io_uring_buf_ring_cq_advance(3)

the whole provided-buffer-ring friend group, iykyk 💅

and that's the whole page, bestie!! 🎀 this one's from the liburing Manual, version liburing-2.6, dated Jan 11, 2024 — mwah, go query that kernel, ily 🫶🌸💖