io_uring_wait_cqe_timeout(3)

💖 io_uring_wait_cqe_timeout — bestie edition 💖

okay so this is a page from the liburing Manual, and it's literally the blueprint for io_uring_wait_cqe_timeout, a little function that sits there and waits for your ring to hand you a completion. no cap, it's giving patient friend energy. 🌸

---

✨ NAME ✨

io_uring_wait_cqe_timeout — bestie, it waits for one io_uring completion event, but with a timeout so you're not stuck waiting forever. 💅

---

🦋 SYNOPSIS 🦋

#include <liburing.h>

int io_uring_wait_cqe_timeout(struct io_uring *ring,
                              struct io_uring_cqe **cqe_ptr,
                              struct __kernel_timespec *ts);

---

💜 DESCRIPTION 💜

so the io_uring_wait_cqe_timeout(3) function is out here waiting for one IO completion to become available from the queue that belongs to the ring param. it'll wait for it if it has to — or it'll wait until the timeout ts expires, whichever comes first. and listen: if an event is already available in the ring when you call it, there is no waiting happening at all. zero. it just hands it over. 🫶

the cqe_ptr param gets filled in on success. that's the whole point, that's your prize. 👑

now here's the tea about ts and kernels. if ts is specified and you're on an older kernel that does not have IORING_FEAT_EXT_ARG, then the application does not need to call io_uring_submit(3) before calling io_uring_wait_cqes(3). but for newer kernels where that feature flag is set, there is no implied submit when you're waiting for a request. so don't go assuming it submitted for you, bestie. 🙈

and if ts is NULL? then this behaves exactly like io_uring_wait_cqe(3) — meaning it will wait forever for an event. forever forever. main character commitment. 😭

---

🌈 RETURN VALUE 🌈

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

and this part matters: the return value tells you the result of waiting for a CQE — it has absolutely no relation to the CQE result itself. two totally different things, don't mix them up. and if a timeout occurs, it will return -ETIME. periodt.

---

👑 SEE ALSO 👑

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

---

that's the whole page, no notes. 💖 this was liburing-2.1, dated November 15, 2021 — go forth and wait on your completions responsibly, ily. 🎀🦋✨