Provided by: libbobcat-dev_4.08.06-1build1_amd64 bug

NAME

       FBB::Selector - Timed delays, Alarms and Multiple File I/O.

SYNOPSIS

       #include <bobcat/selector>
       Linking option: -lbobcat

DESCRIPTION

       FBB::Selector  objects  are  wrappers  around  the  select(2) system calls and allow timed
       delays, alarm functionality and/or  multiple  file  I/O.  It  requires  the  use  of  file
       descriptors,  which are not an official part of C++. However, most operating systems offer
       file descriptors. Sockets are well-known file descriptors.

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned  in  this  man-page,  are
       defined in the namespace FBB.

INHERITS FROM

       -

CONSTRUCTORS

       o      Selector():
              This constructor initializes the object.  The copy constructor is available.

MEMBER FUNCTIONS

       o      void addExceptFd(int fd):
              Adds  a  filedescriptor  to  the  set  of  file  descriptors that are monitored for
              exceptions (note these are not C++ exceptions. See man 2 select for details).

       o      void addReadFd(int fd):
              Adds a filedescriptor to the  set  of  file  descriptors  that  are  monitored  for
              reading.

       o      void addWriteFd(int fd):
              Adds  a  filedescriptor  to  the  set  of  file  descriptors that are monitored for
              writing.

       o      int exceptFd():
              Returns -1 of no more file descriptors are available  in  the  exception  category.
              Otherwise the next available file descriptor in the exception category is returned.
              Returning from wait, this function can be called repeatedly until -1  is  returned,
              servicing each available filedescriptor in turn.

       o      void noAlarm():
              This member prevents any timeout-alarm from occurring.

       o      int nReady():
              Returns  the number of available file descriptors.  0 is returned at a timeout, -1:
              is returned when select(2) itself failed.

       o      int readFd():
              Returns -1 of no more file descriptors are available  for  reading.  Otherwise  the
              next  available  file descriptor for reading is returned. Returning from wait, this
              function can be called repeatedly until -1 is returned,  servicing  each  available
              filedescriptor  in  turn.  Note  that the file whose file descriptor is returned by
              readFd may also be at its end-of-file position. The file is  `ready  for  reading’,
              but  no  characters  will  be  returned  when  trying  to  read  from it due to its
              end-of-file status. In that case the file descriptor is probably best removed  from
              the set of active file descriptors.

       o      void rmExceptFd(int fd):
              Removes  a  filedescriptor  from the set of file descriptors that are monitored for
              exceptions (note these are not C++ exceptions. See man 2 select for details).

       o      void rmReadFd(int fd):
              Removes a filedescriptor from the set of file descriptors that  are  monitored  for
              reading.

       o      void rmWriteFd(int fd):
              Removes  a  filedescriptor  from the set of file descriptors that are monitored for
              writing.

       o      void setAlarm(int sec, int usec = 0):
              This member sets the alarm at the indicated seconds and micro-seconds. If no action
              occurred  on  one of the monitored file descriptions following the indicated amount
              of time, wait will return with nReady returning 0. The requested alarm time (sec  +
              usec / 1e+6) may not be negative and may not exceed std::numeric_limits<int>::max()
              or an FBB::Exception exception will be thrown. A 0 alarm time specification results
              in wait returning immediately. To switch off the alarm time use noAlarm.

       o      int wait():
              This  member  should  be  called  to  wait  for  activities  on  the installed file
              descriptors or timeout-period. The members exceptFd,  nReady,  readFd  and  writeFd
              show their defined behaviors only after wait has returned.

              It  throws  an  FBB::Exception  exception when select(2) fails, which may very well
              indicate the end of any available input. An exception is also thrown if the program
              received a signal.

              If  wait  returns normally its return value represents the number of available file
              descriptors. Note that wait may also return with an input file descriptor  returned
              by  readFd  of a file at its end-of-file position. The file is `ready for reading’,
              but no characters will be  returned  when  trying  to  read  from  it  due  to  its
              end-of-file status.

       o      int writeFd():
              Returns  -1  of  no  more file descriptors are available for writing. Otherwise the
              next available file descriptor for writing is returned. Returning from  wait,  this
              function  can  be  called repeatedly until -1 is returned, servicing each available
              filedescriptor in turn.

EXAMPLE

       #include <string>
       #include <iostream>

       #include <bobcat/selector>
       #include <bobcat/exception>

       using namespace std;
       using namespace FBB;

       int main(int argc, char **argv, char **envp)
       try
       {
           Selector selector;

           selector.setAlarm(5);               // every 5 secs: alarm fires
           selector.addReadFd(STDIN_FILENO);   // look also at cin

           while (true)
           {
               if (!selector.wait())           // 0: alarm fires
                   cout << "Are you still there?" << endl;
               else
               {
                   string s;
                   if (!getline(cin, s) || !s.length())
                       return 0;
                   cout << "Thank you for: " << s << endl;
               }
           }
       }
       catch (Exception const &e)
       {
           cout << e.what() << ’\n’;
           return 1;
       }

FILES

       bobcat/selector - defines the class interface

SEE ALSO

       bobcat(7), select(2)

BUGS

       Not so much a bug as something to be aware of: When removing  input  file  descriptors  of
       files  at their end-of-file positions the set of active file descriptors monitored by wait
       may decay to an empty set. If wait is thereupon called it will wait  forever  since  there
       are  no  more  file  descriptors  to monitor. The monitoring process should check for this
       empty-set situation before calling wait.

       Facilities to prevent wait from waiting indefinitely in this situation will  be  added  to
       Selector in a future Bobcat release.

DISTRIBUTION FILES

       o      bobcat_4.08.06-x.dsc: detached signature;

       o      bobcat_4.08.06-x.tar.gz: source archive;

       o      bobcat_4.08.06-x_i386.changes: change log;

       o      libbobcat1_4.08.06-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.08.06-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms  of  the  GNU  General  Public  License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).