1ivykis(3)                 ivykis programmer's manual                 ivykis(3)
2
3
4

NAME

6       ivykis - library for asynchronous I/O readiness notification
7

DESCRIPTION

9       ivykis is a library for asynchronous I/O readiness notification.  It is
10       a  thin,  portable  wrapper  around  OS-provided  mechanisms  such   as
11       epoll_create(2), kqueue(2), poll(2), poll(7d) (/dev/poll) and port_cre‐
12       ate(3C).
13
14       ivykis was mainly designed for building high-performance network appli‐
15       cations,  but  can  be  used  in any event-driven application that uses
16       poll(2)able file descriptors as its event sources.
17
18       While some programming models dictate using blocking I/O and starting a
19       thread  per event source, programs written to the ivykis API are gener‐
20       ally single-threaded (or use only a small number of threads), and never
21       block  on  I/O.  All input and output is done in a nonblocking fashion,
22       with I/O readiness notifications delivered via callback functions.
23
24       The two main event sources in ivykis are file descriptors  and  timers.
25       File  descriptors  generate  an  event  when  they  become  readable or
26       writable or trigger an error condition, while timers generate an  event
27       when  the  system  time increments past a certain pre-set time.  Events
28       associated with file descriptors  are  level-triggered  --  a  callback
29       function  set  up  to  handle  a  certain file descriptor event will be
30       called repeatedly until the condition generating  the  event  has  been
31       cleared.
32
33       As  mentioned, applications using ivykis are generally single-threaded.
34       Event callbacks are strictly serialised within a thread,  and  non-pre‐
35       emptible.  This mostly removes the need for locking of shared data, and
36       generally simplifies writing applications.
37
38       Each thread that uses ivykis has its own file descriptors  and  timers,
39       and runs a separate event loop.
40
41       In  ivykis, all code that is not initialization code runs from callback
42       functions.  Callback functions are not allowed to block.  If a particu‐
43       lar  piece of code wants to perform a certain operation that can block,
44       it either has to schedule it to run in a separate thread, or it has  to
45       perform  the  operation in a nonblocking fashion instead.  For example,
46       registering an input callback function instead of blocking on  a  read,
47       registering a timer instead of calling sleep(2), etc.
48
49       In case of an internal error, ivykis will use iv_fatal(3) to report the
50       error.  The application can provide a custom  fatal  error  handler  by
51       calling iv_set_fatal_msg_handler(3).
52

SEE ALSO

54       iv_examples(3),   iv_fatal(3),   iv_fd(3),   iv_timer(3),   iv_task(3),
55       iv_init(3), iv_main(3), iv_time(3)
56
57
58
59ivykis                            2010-08-15                         ivykis(3)
Impressum