FBB::Selector(3bobcat)					  Timed Delays, Multiple File I/O				    FBB::Selector(3bobcat)

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 descrip-
	      tions 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 INT_MAX or an FBB::Errno exception (see setAlarm) will be thrown. A 0 alarm time specifica-
	      tion 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::Errno exception when
	      select(2) fails, which may very well indicate the end of any available input. Otherwise it returns  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/errno>

       using namespace std;
       using namespace FBB;

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

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

	   try
	   {
	       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 (Errno const &e)
	   {
	       cout << e.what() << endl;
	   }
	   return 0;
       }

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_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-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).

libbobcat1-dev_3.01.00-x.tar.gz 				     2005-2012						    FBB::Selector(3bobcat)