io_uring_submit_and_wait_reg(3)

💖 io_uring_submit_and_wait_reg — bestie's guide to registered wait regions 💖

okay so this is a page from the liburing Manual — io_uring_submit_and_wait_reg(3), no cap. it sets up and registers fixed wait regions and honestly? it's giving efficiency queen. let's get into it 🫶

---

✨ NAME ✨

io_uring_submit_and_wait_reg — sets up and registers fixed wait regions 💅

---

🌸 SYNOPSIS 🌸

#include <liburing.h>

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

---

🦋 DESCRIPTION 🦋

so the way that io_uring_submit_and_wait_reg(3) works is: it submits all the previously prepared requests chilling in the ring ring, and then it waits for wait_nr completions using the registered wait index of reg_index. and like, upon successful return, the completion events get stored in the cqe_ptr array. iconic behaviour honestly ✨

this function works like io_uring_submit_and_wait_min_timeout(3) in that it supports all the features of that helper — literally all of them, no downgrade — but here's the twist: rather than pass in all the information in a struct that needs copying, it references a registered wait index, and for that index a previously registered wait region holds the info about how the wait should be performed. that includes stuff like the overall timeout, the minimum timeout to be used, and so forth. so basically all the deets live in the region already. see io_uring_setup_register_region(3) for the details on registered regions, specifically for registered wait regions 👑

using registered wait regions has less overhead than other wait methods, because no copying of data is needed. that's the whole point bestie, that's the vibe check it passes 🎀

and yes — it's valid to use this function purely for waiting on events, even if no new requests should be submitted. so if you just wanna sit there and wait, that's a perfectly legal move, main character energy fr fr 💜

---

💅 RETURN VALUE 💅

• On success, io_uring_submit_and_wait_reg(3) returns the number of new requests submitted. slay 🎉
• On failure it returns -errno.
• If the kernel doesn't support this functionality, -EINVAL will be returned. 😭
• If no events are submitted and the wait operation times out, then -ETIME will be returned.

⚠️ heads up bestie: check that return value every single time. -EINVAL here might just mean your kernel isn't in on the plan yet 🙈

---

🔥 SEE ALSO 🔥

• io_uring_register_region(3)
• io_uring_submit_and_wait_min_timeout(3)
• io_uring_submit_and_wait_timeout(3)

---

okay that's the whole page, you ate it, go forth and wait on things efficiently 🧚

this has been liburing-2.9, dated November 2, 2024 — mwah, bye bestie 💖✨