io_uring_prep_msg_ring(3)

✨ io_uring_prep_msg_ring — bestie, it's in the liburing manual 💅

okay so picture this: you've got one ring, and you want to slide a little message into another ring. that's it. that's the whole vibe. this page is from the liburing Manual, and it's about io_uring_prep_msg_ring and its slightly extra sibling. let's get into it 🫶

🌸 NAME 🌸

io_uring_prep_msg_ring — send a message to another ring 💌

🎀 SYNOPSIS 🎀

#include <liburing.h>

void io_uring_prep_msg_ring(struct io_uring_sqe *sqe,
                            int fd,
                            unsigned int len,
                            __u64 data,
                            unsigned int flags);

void io_uring_prep_msg_ring_cqe_flags(struct io_uring_sqe *sqe,
                            int fd,
                            unsigned int len,
                            __u64 data,
                            unsigned int flags,
                            unsigned int cqe_flags);

🦋 DESCRIPTION 🦋

okay so here's the tea ☕

io_uring_prep_msg_ring(3) gets you ready to send a CQE over to an io_uring file descriptor. like, you're the messenger. you're the main character. the submission queue entry sqe gets set up to use the file descriptor fd, and fd must be an io_uring context — no random fds allowed, bestie 🙈 — so it can post a CQE on that ring. and on that target CQE:

• the res field is gonna hold whatever's in len (yes literally the contents of len)
• the user_data gets data
• and the request modifier flags come from flags

important: right now there are no valid flag modifiers, so flags has to be 0. don't be creative, girl. zero. 🚫

the targeted ring can be any ring you have access to — including the ring itself, which is iconic honestly. self-messaging? we love a girl who can entertain herself 💅

this request is lowkey perfect for simple message passing to another ring, and it lets you move 32+64 bits of data through the len and data fields. use cases? literally anything from just waking up someone who's waiting on the targeted ring, to passing actual messages between the two rings. versatile queen 👑

✨ the cqe_flags one ✨

io_uring_prep_msg_ring_cqe_flags(3) is basically io_uring_prep_msg_ring(3)'s cooler cousin. same energy, but it has an additional cqe_flags parameter, and that one sets the flags field on the CQE side. so yeah — you can set the CQE flags field cqe->flags when you send a message 🎀

heads up though: be aware that io_uring could potentially set additional bits into that field. so it's giving "you set some, kernel might set more." not a solo project, it's a collab 🤝

💖 RETURN VALUE 💖

None. like, genuinely none. it's void, she gives nothing back and that's the point 💀

🌈 ERRORS 🌈

these are the errors that show up in the CQE res field, bestie. know them, love them, respect them:

• -ENOMEM — the kernel couldn't allocate memory for the request. it's broke, it's tired, it's not doing it 😭
• -EINVAL — one of the fields you set in the SQE was invalid. check urself before u wreck urself 🙈
• -EBADFD — the descriptor you passed in fd doesn't refer to an io_uring file descriptor, or the ring is in a disabled state. wrong fd, wrong vibe 🚫
• -EOVERFLOW — the kernel couldn't fill a CQE on the target ring. this can happen if the target CQ ring is in an overflow state and the kernel wasn't able to allocate memory for a new CQE entry. crowded ring, no room, sad times 😔

🌟 SEE ALSO 🌟

(this page is from liburing-2.2, dated March 10, 2022 — the era, the moment, the legend.)

okay that's the whole page, bestie, go forth and message your rings responsibly 🫶✨💖🎀🦋🌸💅👑