iv_signal(3)

💖 iv_signal — ivykis signal handling 💖

okay bestie, welcome to the ivykis programmer's manual page for iv_signal (that's section 3, the library-calls girly) ✨ this is literally the whole IV_SIGNAL_INIT, iv_signal_register, iv_signal_unregister situation and I'm gonna walk you through it like we're texting at 2am 🫶

✨ SYNOPSIS ✨

#include <iv_signal.h>

struct iv_signal {
        int             signum;
        unsigned int    flags;
        void            *cookie;
        void            (*handler)(void *);
};

void IV_SIGNAL_INIT(struct iv_signal *this);
int iv_signal_register(struct iv_signal *this);
void iv_signal_unregister(struct iv_signal *this);

🌸 DESCRIPTION 🌸

so iv_signal is the way for your ivykis(3) apps to handle POSIX signals, by gluing them into the ivykis event loop. it's giving "signals but make it event-driven" 💅

if your ivykis app wants signal notifications, you register a struct iv_signal object by calling iv_signal_register, and you only do that after you've initialised it with IV_SIGNAL_INIT and then filled in the ->signum, ->cookie and ->handler members. order matters bestie, no skipping steps 💖

once the signal indicated by ->signum gets delivered to any thread in the current process, the callback you specified in ->handler gets scheduled to be called in the thread that the struct iv_signal object was registered in, with ->cookie as its sole argument. yeah, cross-thread delivery, it's iconic like that ✨

if the same signal arrives again while the callback function is still running, the callback function is guaranteed to be called again after it returns. no lost signals, no cap 😌

now here's a fun one: you're allowed to register multiple struct iv_signal objects for the same signal number. if all of those objects are registered with IV_SIGNAL_FLAG_EXCLUSIVE in ->flags unset, then all the objects will have their callback functions called when the signal arrives — in no guaranteed order, so don't get attached to a sequence, bestie 🙈

invoking callback functions stops at the first struct iv_signal object with IV_SIGNAL_FLAG_EXCLUSIVE in ->flags set. so if literally all the objects have IV_SIGNAL_FLAG_EXCLUSIVE set, only one callback function will be invoked. one. single. callback. 💀

to deinitialize a struct iv_signal object, call iv_signal_unregister from the same thread that iv_signal_register was called from on that object. same thread, always, don't play games 🎀

you are permitted to unregister a struct iv_signal object from any ivykis callback function in the thread it was registered in — including from a callback function triggered by this very object. and yes, you're also permitted to free the memory corresponding to an unregistered object from its own callback function. self-destructing but make it legal 🦋

it is guaranteed that signals delivered to child processes created by fork(2) but that have not yet called execve(2) will not cause iv_signal callbacks to be invoked in the parent process. so the parent stays unbothered, as it should 👑

internally? iv_signal is implemented using iv_event_raw(3). that's the whole secret, iykyk 🤫

⭐ SEE ALSO ⭐

• ivykis(3)
• iv_event_raw(3)
• sigaction(2)

go forth and handle your signals, bestie. register in the right thread, unregister in the right thread, and remember that IV_SIGNAL_FLAG_EXCLUSIVE is the main character that stops the whole callback party 🫶

this page is from the ivykis manual, dated 2010-09-03 — yeah she's vintage but she still slays 💅 🌈