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)