NAME

       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 dispatching the data to the appropriate iohandlers.  The  dispatcher  also
       notifies  iohandlers  of  expired  timers.   Notification 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 provided 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 Dispatcher::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 function will return immediately after checking all file descriptors and
              timers.  The return value will be true if an I/O condition caused the  function  to
              return  and  false  if the function returned because a 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)