Add io_uring_submit_and_wait_min_timeout() man page

Also document the IORING_FEAT_MIN_TIMEOUT flag in io_uring_setup(2)

Signed-off-by: Jens Axboe <[email protected]>

man/io_uring_setup.2

@@ -500,6 +500,12 @@ If this flag is set, then io_uring supports calling
 using a registered ring fd, via
 .BR IORING_REGISTER_USE_REGISTERED_RING .
 Available since kernel 6.3.
+.TP
+.B IORING_FEAT_MIN_TIMEOUT
+If this flag is set, then io_uring supports passing in a minimum batch wait
+timeout. See
+.BR io_uring_submit_and_wait_min_timeout (3)
+for more details.
 
 .PP
 The rest of the fields in the

man/io_uring_submit_and_wait_min_timeout.3

@@ -0,0 +1,105 @@
+.\" Copyright (C) 2021 Stefan Roesch <[email protected]>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_submit_and_wait_min_timeout 3 "Jan 11, 2024" "liburing-2.6" "liburing Manual"
+.SH NAME
+io_uring_submit_and_wait_min_timeout \- submit requests to the submission queue and
+wait for the completion with both batch and normal timeout
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_submit_and_wait_min_timeout(struct io_uring *" ring ","
+.BI "                                         struct io_uring_cqe **" cqe_ptr ","
+.BI "                                         unsigned " wait_nr ","
+.BI "                                         struct __kernel_timespec *" ts ","
+.BI "                                         unsigned int " min_wait_usec ",
+.BI "                                         sigset_t *" sigmask ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_submit_and_wait_min_timeout (3)
+function submits the next requests from the submission queue belonging to the
+.I ring
+and waits for
+.I wait_nr
+completion events, or until the timeout
+.I ts
+expires. The completion events are stored in the
+.I cqe_ptr
+array. The
+.I sigmask
+specifies the set of signals to block. The prevailing signal mask is restored
+before returning. If non-zero,
+.I min_wait_usec
+denotes a timeout for the
+.I wait_nr
+batch.
+
+This works like
+.BR 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
+.BR io_uring_submit_and_wait_timeout (3)
+waits for as long as
+.IR ts
+specifies, or until
+.IR wait_nr
+of request completions have been received, if
+.IR min_wait_usec
+is set, then this is the timeout for the
+.IR wait_nr
+number of requests. If the requested number of completions have been received
+within
+.IR min_wait_usec
+number of microseconds, the the function returns successfully. If that isn't
+the case, once
+.IR 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
+.IR ts
+specified amount of time, subtracting the time already waited. If any
+completions once 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 requests have been posted. It's meant
+to be used to optimize batch waiting for requests, where the application
+allots a budget of
+.IR min_wait_usec
+amount of time to receive
+.IR 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
+.BR IORING_FEAT_MIN_TIMEOUT
+feature flag after the ring has been setup. Ideally used with a ring setup
+with
+.BR 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.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_submit_and_wait_min_timeout (3)
+returns the number of submitted submission queue entries. On failure it returns
+.BR -errno .
+If the kernel doesn't support this functionality,
+.BR -EINVAL
+will be returned. See note on the feature flag.
+The most common failure case is not receiving a completion within the specified
+timeout,
+.B -ETIME
+is returned in this case.
+.SH SEE ALSO
+.BR io_uring_queue_init_params (3),
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_submit_and_wait (3),
+.BR io_uring_submit_and_wait_timeout (3),
+.BR io_uring_wait_cqe (3)