|
HTML rendering created 2025-02-02 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_resize_rings(3) liburing Manual io_uring_resize_rings(3)
io_uring_resize_rings - resize the SQ and CQ rings
#include <liburing.h>
int io_uring_resize_rings(struct io_uring *ring,
struct io_uring_params *p);
The io_uring_resize_rings(3) function performs resizes the SQ
and/or CQ ring associated with ring by the parameters specified in
p .
The p argument must be filled in with the appropriate information
for the resize operations, most notably the sq_entries and
cq_entries fields must be filled out. The flags field can also be
set, see below for potential values that may be used with a resize
operation.
It's fairly uncommon to need to resize the SQ ring, but not that
uncommon that the CQ ring would need resizing. For networked
workloads, it can be hard to appropriately size the CQ ring
upfront, as it's not always known what load a given ring will see.
If overflow conditions are seen for the CQ ring, then resizing it
larger may be a good idea.
When a ring is resized, any pending SQ or CQ entries are copied
along the way. It is not legal to resize a CQ ring that is in an
overflow condition, and attempting to do so will fail.
Currently doesn't support resizing rings setup with
IORING_SETUP_NO_MMAP . This is purely a liburing limitation, the
kernel does support it.
Also note that ring resizing is currently only supported on rings
setup with IORING_SETUP_DEFER_TASKRUN . Attempting to resize
differently configured rings will result in an -EINVAL error.
Valid flags in flags:
IORING_SETUP_CQSIZE
If this isn't set, then the CQ ring size is set based on
the specified SQ ring size. The default is twice as many CQ
ring entries as there are SQ ring entries. If set, then
cq_entries will be used to size the CQ ring.
IORING_SETUP_CLAMP
If set, then SQ and CQ ring entries are clamped to the
maximum allowable size, if they exceed that. If not set,
setting sizes too large will cause the operation to fail.
Other flags are inherited from the way the ring was setup, that
includes flags like IORING_SETUP_NO_SQARRAY , IORING_SETUP_SQE128
, IORING_SETUP_CQE32 , and IORING_SETUP_NO_MMAP .
Other fields in p should be cleared to zero.
Available since kernel 6.13.
Also see io_uring_setup(2) for a detailed description of the setup
flags.
Returns 0 on success, and < 0 on failure. Potential common failure
cases:
-EEXIST
Attempting to resize a ring setup with
IORING_SETUP_SINGLE_ISSUER and the resizing task is
different from the one that created/enabled the ring.
-EFAULT
Copying of p was unsuccessful.
-EINVAL
Invalid flags were specified for the operation
-EINVAL
Attempt to resize a ring not setup with
IORING_SETUP_DEFER_TASKRUN.
-EOVERFLOW
The values specified for SQ or CQ entries would cause an
overflow.
io_uring_setup(2)
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-02-02. (At that time,
the date of the most recent commit that was found in the
repository was 2025-01-22.) 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 October 29, 2024 io_uring_resize_rings(3)
Pages that refer to this page: io_uring_register(2), io_uring_resize_rings(3)
|
HTML rendering created 2025-02-02 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. |
|