Dispatcher  -  wait  on  multiple file descriptors until a
       condition occurs

SYNOPSIS

       #include <Dispatch/dispatcher.h>

DESCRIPTION

       Conceptually, the dispatcher plays the role  of  detecting
       new  data on multiple input file descriptors and dispatch-
       ing the data to  the  appropriate  iohandlers.   The  dis-
       patcher also notifies iohandlers of expired timers.  Noti-
       fication of either an I/O condition or  an  expired  timer
       occurs by calling one of the iohandler's virtual functions
       (see IOHandler(3I)).   Since  a  program  needs  only  one
       instance  of  Dispatcher, a static member function is pro-
       vided to create that instance if necessary and return  it.

PUBLIC OPERATIONS

       enum DispatcherMask { ReadMask, WriteMask, ExceptMask }
       virtual IOHandler* handler(int fd, DispatcherMask)
       virtual void link(int fd, DispatcherMask, IOHandler*)
       virtual void unlink(int fd)
              Return  a  file descriptor's iohandler, link a file
              descriptor  to  an  iohandler,  or  unlink  a  file
              descriptor from its iohandlers.  The DispatcherMask
              describes the I/O condition that the  iohandler  is
              interested  in, such as whether the file descriptor
              has new data available for  reading.   If  the  I/O
              condition occurs, the iohandler will be expected to
              read data from the file descriptor, write  data  to
              the   file  descriptor,  or  handle  the  exception
              depending on the I/O condition.

       virtual void startTimer(long sec, long usec, IOHandler*)
       virtual void stopTimer(IOHandler*)
              Attach an iohandler to a timer or  remove  a  timer
              before it expires.  A timer expires after the given
              number of seconds and  microseconds  have  elapsed.
              If  a timer expires, the dispatcher will notify the
              attached iohandler.  Timers will not  expire  until
              the   program   calls   either   variant   of  Dis-
              patcher::dispatch.

       virtual void dispatch()
       virtual boolean dispatch(long& sec, long& usec)
              With no arguments, block indefinitely until an  I/O
              condition occurs or a timer expires and then notify
              the attached iohandler.  With two arguments,  block
              no  longer  than  the  given  number of seconds and
              microseconds.  If both numbers are zero, the  func-
              tion  will  return  immediately  after checking all
              file descriptors and timers.  The return value will
              timer  expired  or it exceeded the given poll time.
              The function will decrease the given poll  time  by
              the amount of time it spent blocking.

       static Dispatcher& instance()
       static void instance(Dispatcher*)
              With no arguments, create an instance of Dispatcher
              if it doesn't already exist and return it.  With an
              argument,  set the instance of Dispatcher that will
              be used throughout the program.

SEE ALSO

       select(2), IOHandler(3I)