io_uring_wait_cqe(3)

💖 io_uring_wait_cqe — bestie's guide to waiting for your completion 💖

okay so this is a page from the liburing manual, and we're talking about io_uring_wait_cqe(3), which is lowkey one of the most important lil functions in the whole async I/O world. sit down, grab a strawberry 🍓, let's go.

✨ NAME ✨

io_uring_wait_cqe — the way you wait for exactly one io_uring completion event, no more no less, periodt 👑

🎀 SYNOPSIS 🎀

#include <liburing.h>

int io_uring_wait_cqe(struct io_uring *ring,
                      struct io_uring_cqe **cqe_ptr);

look at her. two params. iconic. 💅

🦋 DESCRIPTION 🦋

so the way io_uring_wait_cqe(3) works is, it waits for an IO completion from the queue that belongs to the ring param, and it will genuinely wait for it if it has to. like, it's not gonna ghost you — if the completion isn't ready yet, it just sits there patiently. 🫶

but here's the cute part: if an event is already available in the ring when you call it, then no waiting will occur at all. it just grabs it and goes. slay. no unnecessary drama. ✨

the cqe_ptr param gets filled in on success — that's where your completion event lands, bestie. 🎀

so the whole flow is like: after the caller has submitted a request with io_uring_submit(3), the application can retrieve the completion with io_uring_wait_cqe(3). submit → wait → receive. the holy trinity. the main character arc. 🔥

👑 RETURN VALUE 👑

• On success, io_uring_wait_cqe(3) returns 0 and the cqe_ptr param is filled in. 💖
• On failure, it returns -errno. 😭

⚠️ okay important, don't skip this: the return value indicates the result of waiting for a CQE, and it has no relation to the CQE result itself. like, zero. none. they are two completely different things and confusing them is a vibe check you will fail. the wait succeeded ≠ the operation succeeded. keep them separate fr fr 💀

🌈 SEE ALSO 🌈

• io_uring_submit(3)
• io_uring_wait_cqe_timeout(3)
• io_uring_wait_cqes(3)

and that's the page!! this one's from liburing-2.1, dated November 15, 2021 — so like, vintage but still eating. 💜 go forth and wait for your completions responsibly, bestie. 🧚🌸