io_uring_submit_and_wait_min_timeout(3) — Linux manual page

NAME \| SYNOPSIS \| DESCRIPTION \| RETURN VALUE \| SEE ALSO \| COLOPHON

io_uring_su...min_timeout(3) liburing Manual io_uring_su...min_timeout(3)

NAME top

       io_uring_submit_and_wait_min_timeout - submit requests to the
       submission queue and wait for the completion with both batch and
       normal timeout

SYNOPSIS top

       #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 top

The io_uring_submit_and_wait_min_timeout(3) function submits the
next requests from the submission queue belonging to the ring and
waits for wait_nr completion events, or until the timeout ts
expires. The completion events are stored in the cqe_ptr array. If
non-zero, min_wait_usec denotes a timeout for the wait_nr batch.

The sigmask specifies the set of signals to block. If set, it is
equivalent to atomically executing the following calls:

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);

This works like io_uring_submit_and_wait_timeout(3) with the twist
that it applies a minimum timeout for the requested batch size of
requests to wait for. While io_uring_submit_and_wait_timeout(3)
waits for as long as ts specifies, or until wait_nr of request
completions have been received, if min_wait_usec is set, then this
is the timeout for the wait_nr number of requests. If the
requested number of completions have been received within
min_wait_usec number of microseconds, then 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.

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 as that will
greatly reduce the number of context switches that an application
will see waiting on multiple requests.

Available since 6.12.

RETURN VALUE top

       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 note on the feature flag.  The most
       common failure case is not receiving a completion within the
       specified timeout, -ETIME is returned in this case.

COLOPHON top

       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.8                   Jan 11, 2024  io_uring_su...min_timeout(3)

Pages that refer to this page: io_uring_setup(2), io_uring_submit_and_wait_min_timeout(3), io_uring_submit_and_wait_reg(3), io_uring_wait_cqes_min_timeout(3)