io_uring_resize_rings(3)

💖 io_uring_resize_rings — the glow-up your rings deserve 💖

okay bestie, so this one lives in liburing (that's the manual, the whole liburing vibe, we're in the liburing Manual section rn) and it's genuinely one of the cutest little syscall wrappers out there. it does exactly one thing and it does it slayfully. let's get into it ✨

✨ NAME ✨

io_uring_resize_rings — resize the SQ and CQ rings 🎀

like. it resizes your rings. that's the whole job. no cap.

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_resize_rings(struct io_uring *ring,
                          struct io_uring_params *p);

🦋 DESCRIPTION 🦋

so the io_uring_resize_rings(3) function resizes the SQ and/or CQ ring associated with ring, using the parameters you hand it in p. that's it, that's the function 💅

now, p is not a vibe you can just wing — it 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. you can also set the flags field — scroll down for the values that are actually allowed in a resize operation 👑

lowkey? needing to resize the SQ ring is fairly uncommon. but the CQ ring needing a resize? that is not that uncommon, fr fr. for networked workloads it can be genuinely hard to size the CQ ring appropriately upfront, because you don't always know what load a given ring is gonna see. so if you're seeing overflow conditions on the CQ ring, resizing it larger may be a good idea 🫶

when a ring gets resized, any pending SQ or CQ entries are copied along the way ✨ no data left behind, we love that.

⚠️ it is not legal to resize a CQ ring that is in an overflow condition, and attempting to do so will fail. don't try it, she will not let you 💀

currently, it doesn't support resizing rings setup with IORING_SETUP_NO_MMAP. this is purely a liburing limitation — the kernel does support it, so don't come for the kernel, it's not her fault 🙈

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. that's just how it is rn.

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 it is set, then cq_entries will be used to size the CQ ring. iconic behaviour tbh.
• IORING_SETUP_CLAMP — if set, then SQ and CQ ring entries are clamped to the maximum allowable size if they exceed it. if not set, setting sizes too large will cause the operation to fail. so like, pick your fighter 💅

other flags are inherited from the way the ring was setup, and 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. yes, all of them. zero them. it's giving hygiene ✨

available since kernel 6.13 ⭐

also see io_uring_setup(2) for a detailed description of the setup flags. iykyk.

💜 RETURN VALUE 💜

returns 0 on success, and < 0 on failure. potential common failure cases, bestie, take notes 📝:

• -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. main character said i work alone 😭
• -EFAULT — copying of p was unsuccessful. she could not read your params. tragic.
• -EINVAL — invalid flags were specified for the operation 🚫
• -EINVAL — attempt to resize a ring not setup with IORING_SETUP_DEFER_TASKRUN. yeah, this one again. it's a whole thing.
• -EOVERFLOW — the values specified for SQ or CQ entries would cause an overflow 🫠

👑 SEE ALSO 👑

io_uring_setup(2)

and that's the whole page, no crumbs left 🌸 this was liburing-2.9, dated October 29, 2024, and it's still the same io_uring_resize_rings(3) you know and love. go resize responsibly, bestie, and remember: clear your fields to zero, set DEFER_TASKRUN, and never resize an overflowing CQ ring 💖✨🎀🦋