iv_event_raw(3)

💖 iv_event_raw — bestie edition 💖

ok so this is a page from the ivykis programmer's manual (ivykis, that's the library, hi) and we're talking about iv_event_raw, which is lowkey the ✨cross-boundary queen✨ of event notification. Sit down, hydrate, let's go. 🍓

🌸 NAME 🌸

IV_EVENT_RAW_INIT, iv_event_raw_register, iv_event_raw_unregister, iv_event_raw_post — manage ivykis objects for event notification. That's the whole job, and they do it flawlessly. 💅

🎀 SYNOPSIS 🎀

#include <iv_event_raw.h>

struct iv_event_raw {
        void            *cookie;
        void            (*handler)(void *);
};

void IV_EVENT_RAW_INIT(struct iv_event_raw *this);
int iv_event_raw_register(struct iv_event_raw *this);
void iv_event_raw_unregister(struct iv_event_raw *this);
void iv_event_raw_post(const struct iv_event_raw *this);

look at that struct. two fields. ->cookie and ->handler. minimal. iconic. no notes. 🫶

🦋 DESCRIPTION 🦋

so iv_event_raw gives you a whole way to deliver events to ivykis(3) recipients across thread and process boundaries. like, it does not care where you're calling from. it's that flexible. main character energy fr fr. 💖

Here's the flow, bestie, step by step:

1. The intended event recipient calls IV_EVENT_RAW_INIT on a struct iv_event_raw object.
2. Then it fills in ->cookie and ->handler.
3. Then it calls iv_event_raw_register on that object.

and boom, you're set up. ✨

Now to actually generate an event? You call iv_event_raw_post on the previously initialized struct iv_event_raw object. What happens next is the moment: the callback specified by ->handler gets called in the thread that the struct iv_event_raw object was registered in, with ->cookie as its sole argument. that's it. one argument. no extra baggage. we love a clean interface. 😌

Wanna deinitialize a struct iv_event_raw object? Call iv_event_raw_unregister — and listen, this part matters — from the same thread that iv_event_raw_register was called from on that object. same thread, bestie. don't get cute with it. 🚨

It is permitted to unregister a struct iv_event_raw object from any ivykis callback function in the thread it was registered in, including from a callback function triggered by this object. and yes, it is permitted to free the memory corresponding to an unregistered object from its own callback function. so you can absolutely unalive yourself in your own callback. it's fine. it's allowed. 💀

Now here's where it gets good. iv_event_raw_post can be called from:

• the same thread that iv_event_raw_register was called from ✅
• a different thread in the same process ✅
• or even a different process ✅

and — this is the part that makes people gasp — it can safely be called from signal handlers. not me being obsessed with a function that behaves itself inside a signal handler. 😭🔥

PSA for the optimization girlies: if posting an event only ever needs to be done from within the same process, go look at iv_event(3) instead — it's a lighter-weight alternative to iv_event_raw. don't carry extra weight you don't need. ✨

Okay and now the behind-the-scenes lore, because i know you wanna know how she works internally. 🧚

Internally, iv_event_raw is implemented by registering a file descriptor (a struct iv_fd(3)) with the recipient thread's ivykis event loop, and by causing that file descriptor to become readable upon a call to iv_event_raw_post. yes. that's the trick. readable fd = event delivered. chef's kiss. 👑

And which fd, you ask? Well:

• If eventfd(2) is available, it will be used to procure the abovementioned file descriptor.
• If not, iv_event_raw will fall back to pipe(2) as the source of its file descriptors.

eventfd(2) is preferred because it requires only one file descriptor table entry (while pipe(2) requires two), and it has much less kernel overhead than pipe(2) has. so like, fewer entries, less overhead, more slay. obviously we pick eventfd(2) when we can. 🌈

⭐ SEE ALSO ⭐

• ivykis(3)
• iv_event(3)
• eventfd(2)
• pipe(2)

go read them. iykyk. 📚💜

and that's the whole page, bestie. this one's from the ivykis manual, dated 2010-09-02 — yes she's been serving since 2010 and she has not missed once. 🎀✨💖 periodt.