|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO | COLOPHON |
|
|
|
io_uring_setup_reg_wait(3) liburing Manual io_uring_setup_reg_wait(3)
io_uring_setup_reg_wait - Sets up and registers fixed wait regions
#include <liburing.h>
struct io_uring_reg_wait *io_uring_setup_reg_wait(struct io_uring *ring,
unsigned nentries,
int *err);
The io_uring_setup_reg_wait(3) function allocates and registers a
fixed wait region of nentries entries. Upon successful return, the
function returns a non-NULL pointer. On error, it returns NULL and
fills in err with the error value.
A registered wait region is a contiguous range of
structio_uring_reg_wait, which look as follows:
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];
};
where 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, and sigmask_sz is
the size of the signal mask, if used.
Currently the only valid flag is IORING_REG_WAIT_TS , which, if
set, indicates that the value in ts is valid and should be used
for the wait operation.
A signal mask is used for the wait, if sigmask is set to a valid,
non-zero, pointer value. If used, sigmask_sz must also be set.
Each of the wait regions are indicated by the offset of the
structure. The first wait region is index 0 , the next is index 1
, and so forth, up to the registered number of regions set by
nentries.
The wait regions may be modified by an application at any time
before calling io_uring_submit_and_reg_wait(3). If modified 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.
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.
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.
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.
Available since kernel 6.13.
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.
io_uring_submit_and_wait_reg(3), io_uring_free_reg_wait(3)
This page is part of the liburing (A library for io_uring)
project. Information about the project can be found at
⟨https://github.com/axboe/liburing⟩. If you have a bug report for
this manual page, send it to io-uring@vger.kernel.org. This page
was obtained from the project's upstream Git repository
⟨https://github.com/axboe/liburing⟩ on 2025-08-11. (At that time,
the date of the most recent commit that was found in the
repository was 2025-08-02.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
liburing-2.9 November 2, 2024 io_uring_setup_reg_wait(3)
Pages that refer to this page: io_uring_free_reg_wait(3), io_uring_register_reg_wait(3), io_uring_setup_reg_wait(3), io_uring_submit_and_wait_reg(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|