iohandler(3i) [debian man page]

IOHandler(3I)						    InterViews Reference Manual 					     IOHandler(3I)

NAME

       IOHandler - read input, write output, or handle an I/O exception or timeout

SYNOPSIS

       #include <Dispatch/iohandler.h>

DESCRIPTION

       An iohandler reads data from a file descriptor, writes data to a file descriptor, handles an I/O exception on a file descriptor, or handles
       a timer's expiration.  Once the user has requested the dispatcher to attach an iohandler to a file descriptor or a  timer,  the	dispatcher
       will automatically notify the iohandler when the file descriptor's I/O condition changes or the timer expires.

       For convenience, the user can use a derived generic class (see IOCallback(3I)) to make the iohandler do nothing more than call an arbitrary
       object's member function.

PUBLIC OPERATIONS

       virtual int inputReady(int fd)
       virtual int outputReady(int fd)
       virtual int exceptionRaised(int fd)
	      The dispatcher will call one of these functions to notify an iohandler that it can read data from a file descriptor, write data to a
	      file  descriptor, or handle an I/O exception on a file descriptor.  The iohandler should perform the appropriate action and tell the
	      dispatcher what to do next.  A negative return value means that the iohandler encountered an error or it doesn't	want  to  read	or
	      write  anything  more.   The  dispatcher	will unlink the iohandler from its file descriptor automatically.  A positive return value
	      means that the iohandler didn't read or write everything that it could have.  The dispatcher will call the iohandler again in  round
	      robin  fashion  WITHOUT  checking  select, which means that the iohandler will be called again as soon as the rest of the iohandlers
	      have performed their actions.  A zero return value means that the iohandler finished reading or writing everything it was  able  to.
	      The dispatcher must check the descriptor's status with the select call before it can call the iohandler again.

       virtual void timerExpired(long sec, long usec)
	      The  dispatcher will call this function to notify an iohandler that a timer has expired.	For informational purposes, the parameters
	      give the current time in seconds and microseconds since midnight January 1, 1970.  If the iohandler wants to  reset  the	timer,	it
	      must tell the dispatcher to start another timer.

SEE ALSO

       Dispatcher(3I), IOCallback(3I)

InterViews							  9 January 1991						     IOHandler(3I)

rpoll(3)							  BEGEMOT Library							  rpoll(3)

NAME

       rpoll - callback functions for file descriptors and timers

SYNOPSIS

       # include <rpoll.h>

       typedef void (*poll_f)(int fd, int mask, void *arg);
       typedef void (*timer_f)(int tid, void *arg);

       int poll_register(int fd, poll_f func, void *arg, int mask);

       void poll_unregister(int handle);

       int poll_start_timer(u_int msecs, int repeat, timer_f func,
	    void *arg);

       void poll_stop_timer(int handle);

       int poll_start_utimer(unsigned long long usecs, int repeat,
	    timer_f func, void *arg);

       void poll_dispatch(int wait);

DESCRIPTION

       Many  programs  need  to  read from several file descriptors at the same time.  Typically in these programs one of select(3c) or poll(2) is
       used.  These calls are however clumsy to use and the usage of one of these calls is probably not portable to other systems - not  all  sys-
       tems support both calls.

       The rpoll(l) family of functions is designed to overcome these restrictions.  They support the well known and understood technique of event
       driven programing and, in addition to select(3c) and poll(2) also support timers.

       Each event on a file descriptor or each timer event is translated into a call to a user defined callback function. These functions need	to
       be  registered.	A file descriptor is registered with poll_register.  fd is the file descriptor to watch, mask is an event mask.  It may be
       any combination of POLL_IN to get informed when input on the file descriptor is possible, POLL_OUT to get informed when output is  possible
       or  POLL_EXCEPT	to  get  informed  when an exceptional condition occures.  An example of an exceptional condition is the arrival of urgent
       data.  (Note, that an end of file condition is signaled via POLL_IN).  func is the user function to be called and arg is  a  user  supplied
       argument  for  this function.  The callback functions is called with the file descriptor, a mask describing the actual events (from the set
       supplied in the registration) and the user argument.  poll_register returns a handle, which may be  used  later	to  de-register  the  file
       descriptor.   A	file  descriptor  may  be  registered  more  than  once, if the function, the user arguments or both differ in the call to
       poll_register.  If func and arg are the same, then no new registration is done, instead the event mask of the registration  is  changed	to
       reflect the new mask.

       A registered file descriptor may be de-registered by calling poll_unregister with the handle returned by poll_register.

       A  timer is created with poll_start_timer or poll_start_utimer.	msecs is the number of milliseconds in poll_start_timer while usecs is the
       number of microseconds in poll_start_utimer, after which the timer event will be generated.  If the functions use the poll(2) system  call,
       then  usecs  is rounded to milliseconds and poll_start_timer is called.	repeat selects one-short behavior (if 0) or a repeatable timer (if
       not 0). A one-short timer will automatically unregistered after expiry.	func is the user function which will be called with a timer id and
       the  user  supplied  arg.   poll_start_timer  and  poll_start_utimer  return  a	timer  id,  which  may	be  used  to cancel the timer with
       poll_stop_timer.  A one-short timer should be canceled only if it has not yet fired.

       poll_dispatch must be called to actually dispatch events.  wait is a flag, which should be 0, if only a poll should be done. In this  case,
       the  function  returns,	after  polling	the  registered  file descriptors and timers. If wait is not 0, poll_dispatch waits until an event
       occures. All events are dispatch (i.e. callback functions called) and poll_dispatch returns.

       Typical use is:

	      while(1)
		   poll_dispatch(1);

SEE ALSO

       poll(2),select(3C)

RETURN VALUES

       poll_register , poll_start_timer and poll_start_utimer return a handle which may be used to unregister the file descriptor  or  cancel  the
       timer.

       Both functions and poll_dispatch call xrealloc(l) and can end in panic(l).

ERRORS

       System  call  or  memory  allocation  errors  are  fatal  and  are handle by calling panic(l).  The one exception is a return of EINTR from
       select(3c) or poll(2) in poll_dispatch.	In this case poll_dispatch simply returns.

BUGS

       Obscure sequences of poll_start_timer and poll_stop_timer in callback functions may probably break the code.

       The semantics of POLL_EXCEPT are not clear.

AUTHORS

       Hartmut Brandt, harti@freebsd.org

BEGEMOT 
							    8 Dec 2006								  rpoll(3)