io_uring_sub...wait_timeout(3)

✨ io_uring_submit_and_wait_timeout — from the liburing manual ✨

okay bestie, pull up a chair, we're learning io_uring_submit_and_wait_timeout(3) and honestly? it's giving main character energy. it's a liburing thing. let's go 💅

---

🌸 NAME 🌸

io_uring_submit_and_wait_timeout — submit requests to the submission queue and wait for the completion, but with a timeout clock ticking, so you're never just sitting there forever like a girl waiting for a text back 😭

---

🦋 SYNOPSIS 🦋

#include <liburing.h>

int io_uring_submit_and_wait_timeout(struct io_uring *ring,
                                     struct io_uring_cqe **cqe_ptr,
                                     unsigned wait_nr,
                                     struct __kernel_timespec *ts,
                                     sigset_t *sigmask);

yes that's a whole lot of parameters. she's high maintenance but she delivers ✨

---

💖 DESCRIPTION 💖

so here's the tea, bestie. io_uring_submit_and_wait_timeout(3) does two things at once and it's lowkey iconic for it:

1. it submits the next requests from the submission queue that belong to the ring
2. it waits for wait_nr completion events — or until the timeout ts expires, whichever comes first 🕐

the completion events get stored in the cqe_ptr array. cute, right? no cap.

🎀 the sigmask situation 🎀

the sigmask parameter specifies the set of signals to block. if you set it, it's equivalent to atomically executing these calls:

sigset_t origmask;

pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ret = io_uring_submit_and_wait_timeout(ring, cqe, wait_nr, ts, NULL);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);

so it's the "block the signals, do the thing, put the signals back" dance, except it happens atomically so nothing sneaks in between 🧚

🍓 how you actually use her 🍓

after you grab a submission queue entry (SQE) with io_uring_get_sqe(3) and get that SQE all prepped and ready, you can submit it with io_uring_submit_and_wait_timeout(3). that's the flow, periodt.

👑 the pro-tip setup 👑

ideally you run this with a ring set up using IORING_SETUP_SINGLE_ISSUER|IORING_SETUP_DEFER_TASKRUN, because that will greatly reduce the number of context switches your app sees when it's waiting on multiple requests. fewer context switches = happier app = slay 🔥

---

⭐ RETURN VALUE ⭐

on success, io_uring_submit_and_wait_timeout(3) returns the number of submitted submission queue entries. on failure it returns -errno.

⚠️ heads up though: in earlier versions of the liburing library, the return value was 0 on success. so if you're reading old code and it's checking for 0, that's why. don't come for me, come for the changelog 💀

the most common failure case? not getting a completion within the specified timeout. when that happens, -ETIME gets returned. your vibe check timed out, bestie, it's literally in the name 🙈

---

🌈 SEE ALSO 🌈

go read these next, they're all part of the same friend group:

• io_uring_queue_init_params(3)
• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_submit_and_wait(3)
• io_uring_wait_cqe(3)

---

and that's the whole page, bestie 🫶 this one came from liburing-2.1, dated November 15, 2021. go forth, submit, wait, time out gracefully. i'm obsessed with you. mwah 💜