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 INT_MAX or an FBB::Errno
exception (see setAlarm) 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::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).