io_uring_for_each_cqe(3)

💖 io_uring_for_each_cqe — iterate pending completion events 💖

okay so bestie, welcome to the io_uring_for_each_cqe(3) page from the liburing Manual — yes it's a mouthful, no you don't have to say it out loud, we're gonna get through this together 🫶

✨ SYNOPSIS ✨

#include <liburing.h>

io_uring_for_each_cqe(struct io_uring *ring,
                      unsigned head,
                      struct io_uring_cqe *cqe) { }

🌸 DESCRIPTION 🌸

So. io_uring_for_each_cqe(3) is a macro helper — not a function, a macro, okay — that iterates over the completion events that belong to the ring. It uses head as a temporary iterator, and it points cqe at each pending event while it's iterating. 💅

It's giving efficient, fr fr. The whole point is you loop through all the pending events in the ring in one go, and then you advance the CQ ring by calling io_uring_cq_advance(3) with however many CQEs you actually consumed, once you're done. 👑

And here's the why, because it's lowkey iconic: updating the kernel-visible CQ ring state involves an ordered write. So doing that write once for a whole batch of events is way more efficient than handling each completion separately and calling io_uring_cqe_seen(3) for every single one of them. Batch it, bestie. The kernel will thank you. 🌈

🎀 EXAMPLE 🎀

void handle_cqes(struct io_uring *ring)
{
     struct io_uring_cqe *cqe;
     unsigned head;
     unsigned i = 0;

     io_uring_for_each_cqe(ring, head, cqe) {
          /* handle completion */
          printf("cqe: %d\n", cqe->res);
          i++;
     }

     io_uring_cq_advance(ring, i);
}

see how we count with i and then hand the total to io_uring_cq_advance(3) at the very end? that's the whole vibe. one advance, no cap. ✨

💀 RETURN VALUE 💀

None. Nada. Nothing. It's a macro, she doesn't return, she just does. 🧚

🦋 SEE ALSO 🦋

• io_uring_wait_cqe_timeout(3)
• io_uring_wait_cqe(3)
• io_uring_wait_cqes(3)
• io_uring_cqe_seen(3)
• io_uring_buf_ring_cq_advance(3)

and that's the whole page, bestie 💜 this was liburing-2.4, dated June 04, 2023 — go advance that CQ ring and slay your completions in batches, mwah 🎀💖✨