io_uring_wait_cqe_nr(3)

💖 io_uring_wait_cqe_nr — the liburing manual, bestie edition 💖

okay so you're deep in liburing land and you need your completions to actually, like, arrive. this page is your girl. no cap.

✨ NAME ✨

io_uring_wait_cqe_nr — wait for one or more io_uring completion events 🦋

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_wait_cqe_nr(struct io_uring *ring,
                         struct io_uring_cqe **cqe_ptr,
                         unsigned wait_nr);

💅 DESCRIPTION 💅

so io_uring_wait_cqe_nr(3) hands you back wait_nr IO completion events from the queue that belongs to the ring param, and it will wait for them if it has to. but here's the tea: if the number of events you're asking for is already sitting in the ring when you call it, it does not wait at all. zero patience, love that for it. the cqe_ptr param gets filled in on success. 💖

once you've submitted a request with io_uring_submit(3), your application can go grab the completion with io_uring_wait_cqe(3).

now for the iconic part: ideally you're using this with a ring that was set up with IORING_SETUP_SINGLE_ISSUER|IORING_SETUP_DEFER_TASKRUN, because that combo greatly reduces the number of context switches an application sees while it's waiting on a whole pile of requests. it's giving efficiency. it's giving main character energy. 🔥

⭐ RETURN VALUE ⭐

on success, io_uring_wait_cqe_nr(3) returns 0 and the cqe_ptr param is filled in. on failure it returns -errno. 🙈

okay important thing bestie: the return value is about the result of waiting for a CQE. it has no relation to the CQE result itself. don't mix those up, i'm begging. 😭

🎀 SEE ALSO 🎀

• io_uring_queue_init_params(3)
• io_uring_submit(3)
• io_uring_wait_cqes(3)

this page is from liburing-2.1, dated November 15, 2021 — the io_uring_wait_cqe_nr(3) era, and honestly? iconic. mwah. 💜✨🎀