io_uring_register_iowq_aff(3)

💖 io_uring_register_iowq_aff(3) — the liburing manual 💖

okay bestie, gather round, because this one is about telling your async workers exactly which CPUs they're allowed to vibe on. it lives in the liburing manual, and yes, the whole page is basically "here's how to pin your workers, here's how to unpin them, go off." ✨

🌸 NAME 🌸

io_uring_register_iowq_aff — register async worker CPU affinities

🎀 SYNOPSIS 🎀

#include <sched.h>
#include <liburing.h>

int io_uring_register_iowq_aff(struct io_uring *ring,
                               size_t cpusz,
                               const cpu_set_t *mask);

void io_uring_unregister_iowq_aff(struct io_uring *ring);

🦋 DESCRIPTION 🦋

so, the io_uring_prep_register_iowq_aff(3) function registers a set of CPU affinities that your io_uring async workers are gonna use. by default, io_uring async workers are allowed to run on any CPU in the system — like, total free spirits, no rules, no cap. 🕊️

but if you call this function with ring set to the ring in question, mask set to a pointer to a cpu_set_t value, and cpusz set to the size of the CPU set? then your async workers will only be allowed to run on the CPUs specified in the mask. glow-up complete. 💅

one lil heads up though: existing workers may need to hit a schedule point before they are migrated. so like, they don't teleport instantly, they gotta get to a checkpoint first. patience, babe. 🫶

for unregistration, io_uring_unregister_iowq_aff(3) may be called to restore CPU affinities to the default. back to chaos, we love to see it. 🌈

⚠️ okay this part matters: applications must define _GNU_SOURCE to obtain the definition of this helper, as cpu_set_t will not be defined without it. no _GNU_SOURCE, no cpu_set_t, no function. it's giving locked door and you forgot the key. 🔑

💜 RETURN VALUE 💜

returns 0 on success, or any of the following values in case of error. 😭

• -EFAULT — the kernel was unable to copy the memory pointer to by mask as it was invalid.
• -ENOMEM — the kernel was unable to allocate memory for the new CPU mask.
• -EINVAL — cpusz or mask was NULL/0, or any other value specified was invalid.

👑 SEE ALSO 👑

io_uring_queue_init(3), io_uring_register(2)

and that's the whole page, bestie, you ate that. 🍓 this was brought to you by liburing-2.2, dated March 13, 2022 — iconic since day one, fr fr. 💖✨