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)