Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ex-
	      ception 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,  servic-
	      ing 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	 read-
	      ing. Otherwise the next available	file descriptor	for reading is
	      returned.	Returning from wait, this function can be  called  re-
	      peatedly	 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  re-
	      turned  when  trying to read from	it due to its end-of-file sta-
	      tus. 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 mi-
	      cro-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::nu-
	      meric_limits_int_::max() or an FBB::Exception exception (see se-
	      tAlarm)  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 in-
	      stalled file descriptors	or  timeout-period.  The  members  ex-
	      ceptFd,  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 writ-
	      ing. Otherwise the next available	file descriptor	for writing is
	      returned.	 Returning  from wait, this function can be called re-
	      peatedly	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)
       {
	   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 (Exception 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.25.01-x.dsc: detached signature;

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

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

       o      libbobcat1_3.25.01-x_*.deb:   debian  package  holding  the  li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb: debian package holding  the  li-
	      braries, 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).

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015		FBB::Selector(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | CONSTRUCTORS | MEMBER FUNCTIONS | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=selector&sektion=3bobcat&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help