DragonFly On-Line Manual Pages

Search: Section:  

ivykis(3)                 ivykis programmer's manual                 ivykis(3)


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)

ivykis                            2010-08-15                         ivykis(3)

Search: Section: