io_uring_sub..._min_timeout(3)

✨ NAME ✨

io_uring_submit_and_wait_min_timeout — bestie, this one submits requests to the submission queue and then waits for the completion, and it's got both a batch timeout and a normal timeout. Two timeouts. Iconic.

🎀 SYNOPSIS 🎀

#include <liburing.h>

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

💖 DESCRIPTION 💖

okay so. The io_uring_submit_and_wait_min_timeout(3) function submits the next requests from the submission queue belonging to the ring, and then it waits for wait_nr completion events, or until the timeout ts expires — whichever comes first, bestie. The completion events get stashed in the cqe_ptr array. And if min_wait_usec is non-zero, that's a timeout for the wait_nr batch. 💅

The sigmask specifies the set of signals to block. If it's set, it's equivalent to atomically executing these calls right here:

sigset_t origmask;

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

So here's the twist, and it's giving main character energy: this works like io_uring_submit_and_wait_timeout(3), except it applies a minimum timeout for the requested batch size of requests to wait for. Let me break it down fr fr.

io_uring_submit_and_wait_timeout(3) waits for as long as ts says, or until wait_nr request completions have been received. But if min_wait_usec is set, then that is the timeout for the wait_nr number of requests. Here's the whole vibe check:

• If the requested number of completions have been received within min_wait_usec number of microseconds → the function returns successfully. 🎉
• If that isn't the case → once min_wait_usec time has passed, control is returned if any completions have been posted.
• If no completions have been posted → the kernel switches to a normal wait of up to ts specified amount of time, subtracting the time already waited.
• If any completions are posted after this happens → control is returned immediately to the application. 🫶

This differs from the normal timeout waiting in that waiting continues post the initial timeout, if and only if no completions have been posted. It's meant to be used to optimize batch waiting for requests, where the application allots a budget of min_wait_usec amount of time to receive wait_nr number of completions, but if none are received, then waiting can continue without incurring extra context switches or extra kernel/user transitions. no cap, that's the whole point. 🔥

Can be used with any ring, as long as the kernel supports it. Support is indicated by checking the IORING_FEAT_MIN_TIMEOUT feature flag after the ring has been setup. Ideally used with a ring setup with IORING_SETUP_SINGLE_ISSUER|IORING_SETUP_DEFER_TASKRUN, because that will greatly reduce the number of context switches that an application will see waiting on multiple requests. 👑

Available since 6.12. 🦋

⭐ RETURN VALUE ⭐

On success, io_uring_submit_and_wait_min_timeout(3) returns the number of submitted submission queue entries. On failure it returns -errno. If the kernel doesn't support this functionality, -EINVAL will be returned — see the note on the feature flag, bestie. 👀

The most common failure case is not receiving a completion within the specified timeout, and -ETIME is returned in this case. 😭

🌸 SEE ALSO 🌸

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

and that's the whole page, bestie 💜 this lil beauty lives in liburing-2.8, dated Jan 11, 2024, and it's a total slay. go forth and wait on your completions responsibly. ✨🎀🦋