io_uring_register_eventfd(3)

💖 io_uring_register_eventfd(3) — the liburing bestie guide 💖

okay so bestie, this is a page from the liburing manual, and it's about wiring an eventfd up to your ring so you get lil notifications when stuff finishes. it's short, it's sweet, it's lowkey iconic. let's go 🦋

---

🌸 NAME 🌸

io_uring_register_eventfd — register an eventfd with a ring

like... you're handing the ring a little doorbell. that's the whole vibe. 🔔

---

✨ SYNOPSIS ✨

#include <liburing.h>

int io_uring_register_eventfd(struct io_uring *ring,
                              int fd);

int io_uring_register_eventfd_async(struct io_uring *ring,
                                    int fd);

int io_uring_unregister_eventfd(struct io_uring *ring);

three functions, three moods: register, register but async-only, and unregister. pick your fighter 💅

---

🎀 DESCRIPTION 🎀

io_uring_register_eventfd(3) registers the eventfd file descriptor fd with the ring that ring points at. that's it, that's the registration. so official. so demure. 🫶

and then?? the good part: whenever completions get posted to the CQ ring, an eventfd notification is generated using that registered eventfd descriptor. so your eventfd is basically the ring's group chat — it pings you when things are done. 🔥

but wait, there's a plot twist: if you use io_uring_register_eventfd_async(3) instead, then only the events that completed out-of-line will trigger a notification. so it's the selective-notifications version. main character energy, only shows up for the dramatic stuff. ✨

and if you're over it — notifications no longer desired, no cap — you can call io_uring_unregister_eventfd(3) to remove the eventfd registration. heads up: you do not pass an eventfd argument, because a ring can only have a single eventfd registered. one ring, one eventfd, monogamy fr fr 💀

---

👑 NOTES 👑

okay this part is important so pay attention bestie, i'm being so serious rn 😭

so io_uring generally takes care to avoid spurious events — key word: generally. they can still occur. 🙈

similarly, batched completions of CQEs may only trigger a single eventfd notification, even if multiple CQEs are posted. like, five CQEs walk into the ring and the doorbell rings once. rude but legal.

so your application should make no assumptions about the number of events being available having a direct correlation to the eventfd notifications posted.

which means: an eventfd notification must only be treated as a hint to go check the CQ ring for completions. it's a vibe check, not a receipt. 💅

---

⭐ RETURN VALUE ⭐

returns 0 on success, or -errno on error. classic. no notes. 💖

---

🌈 SEE ALSO 🌈

• eventfd(2)

---

and that's the whole page babes 🧚 this was the liburing-2.2 manual, dated April 16, 2022, and it was io_uring_register_eventfd(3) all along. go ring your doorbell. mwah 💜