Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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_cre-
       ate(3C).

       ivykis was mainly designed for building high-performance	network	appli-
       cations,	 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	gener-
       ally 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-pre-
       emptible.  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 particu-
       lar  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)

NAME | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ivykis&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help