iv_event(3)

💖 iv_event(3) — the ivykis programmer's manual, but make it cute 💖

okay bestie, so this is iv_event(3) from the ivykis programmer's manual, and it's literally the whole guide to cross-thread event notification. no cap. let's get into it 🦋

✨ NAME ✨

IV_EVENT_INIT, iv_event_register, iv_event_unregister, iv_event_post — manage ivykis objects for event notification 🎀

🌸 SYNOPSIS 🌸

#include <iv_event.h>

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

int IV_EVENT_INIT(struct iv_event *this);
int iv_event_register(struct iv_event *this);
void iv_event_unregister(struct iv_event *this);
void iv_event_post(struct iv_event *this);

👑 DESCRIPTION 👑

iv_event is the way to deliver events to ivykis(3) recipients across thread boundaries. it's giving inter-thread communication, it's giving "my other thread has something to tell you" 💅

so here's the whole vibe. the thread that's supposed to receive the event — the intended recipient — does this:

1. calls IV_EVENT_INIT on a struct iv_event object
2. fills in ->cookie and ->handler
3. calls iv_event_register on the object

that's the setup, and it ate, no crumbs 🍓

now, to actually generate an event? call iv_event_post on the struct iv_event object you already initialized. what happens next is the moment ✨: the callback you specified in ->handler gets called in the thread that the struct iv_event object was registered in, and its sole argument is ->cookie. periodt.

to deinitialize a struct iv_event object, call iv_event_unregister — and listen, this has to happen from the same thread that iv_event_register was called from on that object. like, same thread. iykyk 🙈

but here's the fun part, and it's lowkey iconic:

• it is permitted to unregister a struct iv_event object from any ivykis callback function, as long as you're in the thread it was registered in — including from a callback function that was triggered by this very object 🔥
• and it is permitted to free the memory of an unregistered object from its own callback function. main character energy honestly 💀

okay so where can you call iv_event_post from? let's vibe check that:

• ✅ from the same thread that iv_event_register was called from
• ✅ from a different thread, as long as it's within the same process
• ❌ can not be called from a different process
• ❌ can not be called from signal handlers

🚨 if you need that functionality, bestie, go look at iv_event_raw(3). it's the one for you.

and the tea on how it works under the hood 🫖: internally, iv_event is implemented as a wrapper around iv_event_raw(3), and it multiplexes multiple struct iv_event objects over per-thread struct iv_event_raw objects — all so it can save file descriptors and kernel resources. efficient queen 💜

🌈 SEE ALSO 🌈

• ivykis(3)
• iv_event_raw(3)

that's the whole page, bestie, you're so welcome 🫶 ivykis, dated 2010-09-03 — yeah she's an oldie but she's a classic, and she's still slaying ✨💖🎀