iv_fd(3)

💖 iv_fd(3) — bestie's guide to ivykis file descriptors 💖

okay so this is the ivykis programmer's manual page for all the fd girlies. the functions in here are iv_fd_register, iv_fd_register_try, iv_fd_unregister, iv_fd_registered, iv_fd_set_handler_in, iv_fd_set_handler_err and iv_fd_set_handler_out — they're literally the whole "deal with ivykis file descriptors" situation. no cap. 🌸

✨ SYNOPSIS ✨

#include <iv.h>

struct iv_fd {
        int             fd;
        void            *cookie;
        void            (*handler_in)(void *);
        void            (*handler_out)(void *);
        void            (*handler_err)(void *);
};

void IV_FD_INIT(struct iv_fd *fd);
void iv_fd_register(struct iv_fd *fd);
int iv_fd_register_try(struct iv_fd *fd);
void iv_fd_unregister(struct iv_fd *fd);
int iv_fd_registered(const struct iv_fd *fd);
void iv_fd_set_handler_in(struct iv_fd *fd, void (*handler)(void *));
void iv_fd_set_handler_out(struct iv_fd *fd, void (*handler)(void *));
void iv_fd_set_handler_err(struct iv_fd *fd, void (*handler)(void *));

🦋 DESCRIPTION 🦋

so iv_fd_register and iv_fd_unregister are the register/unregister duo for a file descriptor with the current thread's ivykis event loop. and then iv_fd_registered, when you call it on a file descriptor, hands you back true if that fd is, like, currently registered with ivykis. simple as that. 💅

when an fd that's registered with ivykis becomes ready for input or output, or an error condition pops off on it, and a callback function for that event has been specified — that callback gets called in the thread the fd was registered in. periodt.

and conversely (love a conversely): when an fd that's already ready for input or output, or already has an error condition set, gets registered with ivykis, and the corresponding callback function pointer is not NULL, then that callback will be called in the next iteration of the current thread's ivykis event loop. not me being proactive about it bestie, it just does that. 🔥

before a file descriptor is registered, it must have been initialised by calling IV_FD_INIT on it, and it must have had its ->fd member field set to a valid OS file descriptor. the ->handler_in, ->handler_out and ->handler_err member fields point to callback functions that get called when the specified fd becomes ready for input or output or an error condition occurs. if any handler function is set to NULL, that's the app saying "not interested in being notified about the corresponding event", tyvm. 🙈

an application is not allowed to change the ->fd member while a file descriptor is registered. do not do it. i'm serious. 💀

iv_fd_set_handler_in changes the callback function that gets called when descriptor fd becomes ready for input. and listen — an application is not allowed to directly change the ->handler_in member after the fd has been registered, you have to use this function instead. conversely (again, iconic), it's not allowed to use this function before the fd has been registered. timing is everything, bestie. 🎀

iv_fd_set_handler_out is the same vibe as iv_fd_set_handler_in, only it handles the callback function for output readiness (->handler_out).

iv_fd_set_handler_err is also the same vibe as iv_fd_set_handler_in and iv_fd_set_handler_out, only it handles the callback function for error conditions (->handler_err).

okay now this part is very slay: when a handler function was NULL, and it got set to a non-NULL value by calling iv_fd_set_handler_in, iv_fd_set_handler_out or iv_fd_set_handler_err, and the file descriptor was already ready for input or output, or already had an error condition set — an event is generated, and the specified callback function will be called in the next iteration of the current thread's event loop. so the application does not need to poll the fd to check if a condition was already raised. it's giving effortless. ✨

callback functions get passed a cookie value as their first and sole argument. if the application wants to use this facility for transferring data to the callback function, it should set the ->cookie member of a file descriptor to a value of type void *. and this value can be modified directly by the application at any time, no helper function required. main character energy fr fr. 🫶

when a file descriptor is registered with ivykis, it's transparently set to nonblocking mode, and configured to be closed on exit(3). yes, automatically. obsessed. 🌈

an application is allowed to unregister a file descriptor from within any callback function — including callback functions triggered by that file descriptor itself — and even to free the memory corresponding to that fd from any callback function. but a struct iv_fd can only be unregistered in the thread that it was registered from. rules are rules. ⭐

it's allowed to register the same underlying OS file descriptor in multiple threads, but a given struct iv_fd can only be registered in one thread at a time. 💜

iv_fd_register does not return errors to the caller, and if there's an error while registering the fd — for example if it isn't open or is unpollable — iv_fatal(2) will be invoked. 😭 so if you don't know whether registering the file descriptor with the kernel is gonna work out, use iv_fd_register_try instead. it's a variant on iv_fd_register that returns a nonzero value in case of a registration error. but heads up: since iv_fd_register_try disables various internal optimisations, it is recommended to use iv_fd_register whenever possible. like, whenever possible possible. 👑

see iv_examples(3) for programming examples. 🍓

🧚 SEE ALSO 🧚

• ivykis(3)
• iv_examples(3)

and that's the whole page bestie 💖 this one came from ivykis, dated 2010-08-15. go forth and register responsibly. 🎀✨👑