io_uring_prep_futex_waitv(3)

💖 io_uring_prep_futex_waitv — bestie edition 💖

okay so this is a page from the liburing Manual, section 3, and it's all about io_uring_prep_futex_waitv. yes the name is a mouthful, no we are not shortening it, it's iconic actually 🎀

---

✨ NAME ✨

io_uring_prep_futex_waitv — get ready to wait on a whole squad of futexes at once, not just one 💅

---

🌸 SYNOPSIS 🌸

#include <linux/futex.h>
#include <unistd.h>
#include <liburing.h>

void io_uring_prep_futex_waitv(struct io_uring_sqe *sqe,
                               const struct futex_waitv *futexv,
                               uint32_t nr_futex,
                               unsigned int flags);

---

🦋 DESCRIPTION 🦋

so here's the vibe: io_uring_prep_futex_waitv(3) sets you up with a futex wait request that covers multiple futexes at the same time. like, all of them. at once. multitasking queen energy 👑

the submission queue entry sqe gets prepped for waiting on every futex listed in futexv, and nr_futex tells it how many futexes are actually chillin' in that array. and flags? flags has to be set to the io_uring-specific futex flags, no freelancing.

here's the lil plot twist: unlike io_uring_prep_futex_wait(3), the bitset mask and the values you want are passed inside futexv. not as separate args. it's giving "everything's in the bag already" 👜

and about those flags — they're currently unused, so you literally have to pass 0. that's it. that's the whole assignment.

this function prepares an async futex(2) waitv request, so go read that man page for the details, bestie.

⭐ Available since kernel 6.7. no cap, don't try this on your grandma's kernel.

---

💜 RETURN VALUE 💜

None. nothing. zero. it returns void, so there's nothing to catch here 🫶

---

😭 ERRORS 😭

the CQE res field is where the actual result of the operation shows up — check the related man page for the possible values, iykyk.

and now the important part, because this trips everyone up the first time: where synchronous system calls would return -1 on failure and set errno to the real error value, io_uring never uses errno. instead it hands you the negated errno directly, right there in the CQE res field. so like, -EAGAIN and not -1. periodt 💀

---

🧚 NOTES 🧚

here's the thing about the sync futex syscalls — they let you wait on a futex with a timeout. io_uring does not support passing in a timeout for this request. not a thing. nope.

so what do you do instead? applications are encouraged to use a linked timeout to abort the futex request at a given time, if that's what you want. that's the move, that's the workaround, that's the main character solution ✨

---

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_prep_futex_wait(3)
• io_uring_prep_futex_wake(3)
• io_uring_prep_link_timeout(3)
• futex(2)
• futex2(2)

---

okay that's the whole page, you ate it, you understood it, you're basically a kernel dev now 🎀💖

this was liburing-2.5, dated Sep 29, 2023 — mwah, go submit some futexes, bestie 🦋✨