NAME¶
ivykis - library for asynchronous I/O readiness notification
DESCRIPTION¶
ivykis is a library for asynchronous I/O readiness notification. It is a thin,
portable wrapper around OS-provided mechanisms such as
epoll_create(2),
kqueue(2),
poll(2),
poll(7d) (/dev/poll) and
port_create(3C).
ivykis was mainly designed for building high-performance network applications,
but can be used in any event-driven application that uses
poll(2)able
file descriptors as its event sources.
While some programming models dictate using blocking I/O and starting a thread
per event source, programs written to the ivykis API are generally
single-threaded (or use only a small number of threads), and never block on
I/O. All input and output is done in a nonblocking fashion, with I/O readiness
notifications delivered via callback functions.
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, while timers generate an event when the system time
increments past a certain pre-set time. Events associated with file
descriptors are level-triggered -- 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.
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.
Each thread that uses ivykis has its own file descriptors and timers, and runs a
separate event loop.
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.
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).
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)