ivykis(3)

💖 NAME 💖

ivykis — bestie, it's a library for asynchronous I/O readiness notification ✨

🦋 DESCRIPTION 🦋

okay so. ivykis is a library for asynchronous I/O readiness notification, and it lives in the ivykis programmer's manual 💅 It's basically a thin, portable wrapper around whatever mechanism your OS already ships, like epoll_create(2), kqueue(2), poll(2), poll(7d) (/dev/poll) and port_create(3C). So you write one vibe, and it slays on every platform 🫶

ivykis was mainly designed for building high-performance network applications 👑 but like, it can be used in any event-driven application that uses poll(2)able file descriptors as its event sources. no gatekeeping here 💖

so some programming models are all "block on I/O and spin up a whole thread per event source" and honestly? that's giving chaos 😭 Programs written to the ivykis API are generally single-threaded (or use only a small number of threads), and they never block on I/O. All input and output is done in a nonblocking fashion, with I/O readiness notifications delivered via callback functions. that's the whole vibe ✨

The two main event sources in ivykis are file descriptors and timers 🎀

• file descriptors generate an event when they become readable or writable or trigger an error condition
• timers generate an event when the system time increments past a certain pre-set time

Events associated with file descriptors are level-triggered — meaning a callback function set up to handle a certain file descriptor event will be called repeatedly until the condition generating the event has been cleared. she will keep showing up until you deal with her, periodt 💅

As mentioned, applications using ivykis are generally single-threaded. Event callbacks are strictly serialised within a thread, and non-preemptible. This mostly removes the need for locking of shared data, and generally simplifies writing applications. no mutex drama, we love to see it 😌✨

Each thread that uses ivykis has its own file descriptors and timers, and runs a separate event loop. everybody's got their own little ecosystem 🌸

In ivykis, all code that is not initialization code runs from callback functions. Callback functions are not allowed to block 🚫 If a particular piece of code wants to perform a certain operation that can block, it either has to schedule it to run in a separate thread, or it has to perform the operation in a nonblocking fashion instead. For example:

• registering an input callback function instead of blocking on a read
• registering a timer instead of calling sleep(2)
• etc.

it's giving ✨main character energy✨, not ✨waiting in line energy✨ 🧚

💀 heads up bestie: in case of an internal error, ivykis will use iv_fatal(3) to report the error. The application can provide a custom fatal error handler by calling iv_set_fatal_msg_handler(3). so if you wanna control how the meltdown looks, that's your moment 🎀

🌈 SEE ALSO 🌈

• iv_examples(3)
• iv_fatal(3)
• iv_fd(3)
• iv_timer(3)
• iv_task(3)
• iv_init(3)
• iv_main(3)
• iv_time(3)

and that's the whole page, bestie!! 🫶 this one is ivykis, dated 2010-08-15, from the ivykis source 🎀 go build something iconic with it 💖✨👑