io_uring_peek_cqe(3)

💖 io_uring_peek_cqe — liburing manual, but make it cute ✨

okay bestie, pull up a chair 🪑 because we're talking about io_uring_peek_cqe(3) — yes it's a real function, yes it lives in the liburing manual, and yes it's about to be your new fave 💅

✨ NAME ✨

io_uring_peek_cqe — literally just checking if an io_uring completion event is ready for you, no waiting, no drama 🌸

🎀 SYNOPSIS 🎀

#include <liburing.h>

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

unsigned io_uring_peek_batch_cqe(struct io_uring *ring,
                                 struct io_uring_cqe **cqe_ptrs,
                                 unsigned count);

two functions, one vibe. one peeks a single CQE, the other peeks a whole little squad of them 🫶

💜 DESCRIPTION 💜

okay so first up, io_uring_peek_cqe(3). this function returns an IO completion from the queue that belongs to the ring param — but only if one is already sitting there, readily available 👀. on a successful return, the cqe_ptr param gets filled with a valid CQE entry, and you're good to go ✨.

here's the important part, bestie: this function does not enter the kernel to wait for an event. like, it will not go knock on the kernel's door and be like "hello?? any completions??" 🙈. an event is only returned if it's already available in the CQ ring. it's giving "if you know, you know" — if it's there, you get it, if it's not, you don't 💀.

then we have io_uring_peek_batch_cqe(3), the group-chat version 📱. it returns up to count request completions in cqe_ptrs, belonging to the ring param, if they're readily available. same energy as above — it will not enter the kernel, unless the CQ ring is in an overflow condition 😳 (that's the one exception, don't forget it). upon successful return, cqe_ptrs are filled with the number of events indicated by the return value. iconic behaviour, no cap 👑

🌈 RETURN VALUE 🌈

• on success, io_uring_peek_cqe(3) returns 0, and the cqe_ptr parameter is filled in 💖
• on success, io_uring_peek_batch_cqe(3) returns the number of completions that got filled in 🔥
• on failure, io_uring_peek_cqe(3) may return -EAGAIN 😭 (that's the "nothing here yet, try again later" vibe, not a crisis)

🦋 SEE ALSO 🦋

• io_uring_submit(3)
• io_uring_wait_cqes(3)
• io_uring_wait_cqe(3)

go read those too, they're all part of the same friend group 💅✨

and that's the whole page, bestie 🎀 this one's from liburing-2.2, dated March 12, 2022 — so you know it's been serving reliable peek energy since then 👑🫶 periodt.