io_uring_setup_reg_wait(3)

💖 io_uring_setup_reg_wait(3) 💖

okay bestie, so this one lives in the liburing Manual, and it's lowkey the setup step for the whole "fixed wait regions" situation. Let's get into it ✨

✨ NAME ✨

io_uring_setup_reg_wait — Sets up and registers fixed wait regions 🎀

🌸 SYNOPSIS 🌸

#include <liburing.h>

struct io_uring_reg_wait *io_uring_setup_reg_wait(struct io_uring *ring,
                                                  unsigned nentries,
                                                  int *err);

🦋 DESCRIPTION 🦋

so io_uring_setup_reg_wait(3) goes and allocates and registers a fixed wait region of nentries entries. If it works, you get a non-NULL pointer back, slay. If it doesn't, you get NULL and it fills in err with the error value. that's the whole deal 💅

A registered wait region is literally just a contiguous range of structio_uring_reg_wait, and they look like this:

struct io_uring_reg_wait {
    struct __kernel_timespec ts;
    __u32                    min_wait_usec;
    __u32                    flags;
    __u64                    sigmask;
    __u32                    sigmask_sz;
    __u32                    pad[3];
    __u64                    pad2[2];
};

breaking that down for you bestie:

• ts is the wait related information for this wait 👑
• min_wait_usec is the minimum wait period (for a two-stage wait), if set to non-zero
• flags tells the kernel about the wait region
• sigmask is a pointer to a signal mask, if used
• sigmask_sz is the size of the signal mask, if used

rn the only valid flag is IORING_REG_WAIT_TS, which — if you set it — is saying "hey, the value in ts is valid and should be used for the wait operation." periodt ✨

A signal mask gets used for the wait if sigmask is set to a valid, non-zero, pointer value. And if you're using it, sigmask_sz must also be set. no skipping that step, okay? 🙈

Each of the wait regions is indicated by the offset of the structure. so the first wait region is index 0, the next is index 1, and so on and so forth, all the way up to the registered number of regions set by nentries. it's giving numbered lockers at the mall 🎀

the wait regions may be modified by an application at any time before calling io_uring_submit_and_reg_wait(3). If you modify one while a wait region for that given offset is currently in use by the kernel, the results are undefined — the kernel may see the new value in time to use it, or it may not. literally a coin flip, don't do it 😭

The main purpose of registered wait regions and the associated submit-and-wait helpers is to reduce the overhead of a wait operation. A normal wait for events with a timeout will pass in a structio_uring_getevents_arg which will need to be copied for each wait. For high frequency wait operations, this adds noticeable overhead for each wait. With registered wait regions, no such copying needs to take place for each wait. it's the "stop re-typing your address at checkout" of syscalls fr fr 🫶

Once a wait region has been setup, it persists for the life time of the ring. It's currently not possible to unregister or resize a wait region. Additionally, a wait region may currently only use a single page of memory. On a 4k page size system, this means an application is limited to 64 wait regions. That should be enough, as each wait index may be modified as needed. With at least 64 indices available, hopefully applications can just use the appropriately setup wait region for each specific type of wait, with different indices having different wait settings. one region per vibe, iykyk 💜

While a region cannot get unregistered from the kernel, once a ring has been closed, the application may free the associated memory by calling io_uring_free_reg_wait(3). An application may also do this before closing a ring, but then wait regions may no longer be modified by the application. choose your moment wisely bestie ⭐

Available since kernel 6.13. 🔥

🌈 RETURN VALUE 🌈

On success io_uring_setup_reg_wait(3) returns a pointer to the start of the wait regions. On failure, it returns NULL and sets err to the appropriate -errno value. simple as that 💅

🎀 SEE ALSO 🎀

• io_uring_submit_and_wait_reg(3)
• io_uring_free_reg_wait(3)

and that's the whole page bestie, no cap. this gorgeous little manual came from liburing-2.9, dated November 2, 2024 — so when you cite it, cite it with your whole chest 💖✨🦋👑