.TH "FBB::Selector" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Timed Delays, Multiple File I/O"

.PP 
.SH "NAME"
FBB::Selector \- Timed delays, Alarms and Multiple File I/O\&.
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/selector>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
\fBFBB::Selector\fP objects are wrappers around the \fBselect\fP(2) system
calls and allow timed delays, alarm functionality and/or multiple file I/O\&. It
requires the use of \fIfile descriptors\fP, which are not an official part of
\fBC++\fP\&. However, most operating systems offer \fIfile descriptors\fP\&. Sockets
are well\-known file descriptors\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "CONSTRUCTORS"
.IP o 
\fBSelector()\fP:
.br 
This constructor initializes the object\&.

.PP 
Copy and move constructors (and assignment operators) are available\&.
.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBvoid addExceptFd(int fd)\fP:
.br 
Adds a filedescriptor to the set of file descriptors that are
monitored for exceptions (note these are not \fBC++\fP exceptions\&. See \fIman 2
select\fP for details)\&.
.IP o 
\fBvoid addReadFd(int fd)\fP:
.br 
Adds a filedescriptor to the set of file descriptors that are
monitored for reading\&.
.IP o 
\fBvoid addWriteFd(int fd)\fP:
.br 
Adds a filedescriptor to the set of file descriptors that are
monitored for writing\&.
.IP o 
\fBint exceptFd()\fP:
.br 
Returns \-1 of no more file descriptors are
available in the \fIexception\fP category\&. Otherwise the next available file
descriptor in the \fIexception\fP category is returned\&. Returning from
\fIwait\fP, this function can be called repeatedly until \-1 is returned,
servicing each available filedescriptor in turn\&.
.IP o 
\fBvoid noAlarm()\fP:
.br 
This member prevents any timeout\-alarm from occurring\&.
.IP o 
\fBint nReady()\fP:
.br 
Returns the number of available file descriptors\&.  0 is returned at a
timeout, \-1: is returned when \fIselect\fP(2) itself failed\&.
.IP o 
\fBint readFd()\fP:
.br 
Returns \-1 of no more file descriptors are available for
reading\&. Otherwise the next available file descriptor for reading is
returned\&. Returning from \fIwait\fP, 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 \fIreadFd\fP may also be at
its end\-of\-file position\&. The file is `ready for reading\(cq\&, 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\&.
.IP o 
\fBvoid rmExceptFd(int fd)\fP:
.br 
Removes a filedescriptor from the set of file descriptors that are
monitored for exceptions (note these are not \fBC++\fP exceptions\&. See \fIman 2
select\fP for details)\&.
.IP o 
\fBvoid rmReadFd(int fd)\fP:
.br 
Removes a filedescriptor from the set of file descriptors that are
monitored for reading\&.
.IP o 
\fBvoid rmWriteFd(int fd)\fP:
.br 
Removes a filedescriptor from the set of file descriptors that are
monitored for writing\&.
.IP o 
\fBvoid setAlarm(int sec, int usec = 0)\fP:
.br 
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, \fIwait\fP will return with \fInReady\fP
returning 0\&. The requested alarm time (\fIsec + usec / 1e+6\fP) may not be
negative and may not exceed \fIstd::numeric_limits<int>::max()\fP or an
\fIFBB::Exception\fP exception will be thrown\&. A 0 alarm time specification
results in \fIwait\fP returning immediately\&. To switch off the alarm time use
\fInoAlarm\fP\&.
.IP o 
\fBint wait()\fP:
.br 
This member should be called to wait for activities on the installed
file descriptors or timeout\-period\&. The members \fIexceptFd, nReady, readFd\fP
and \fIwriteFd\fP show their defined behaviors only after \fIwait\fP has returned\&.
.IP 
It throws an \fIFBB::Exception\fP exception when \fBselect\fP(2) fails, which may
very well indicate the end of any available input\&. An exception is also thrown
if the program received a signal\&.
.IP 
If \fIwait\fP returns normally its return value represents the number of
available file descriptors\&. Note that \fIwait\fP may also return with an input
file descriptor returned by \fIreadFd\fP of a file at its end\-of\-file
position\&. The file is `ready for reading\(cq\&, but no characters will be returned
when trying to read from it due to its end\-of\-file status\&.
.IP 
.IP o 
\fBint writeFd()\fP:
.br 
Returns \-1 of no more file descriptors are available for
writing\&. Otherwise the next available file descriptor for writing is
returned\&. Returning from \fIwait\fP, this function can be called repeatedly
until \-1 is returned, servicing each available filedescriptor in turn\&.

.PP 
.SH "EXAMPLE"
.nf 

#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 << \(dq\&Are you still there?\(dq\& << endl;
        else
        {
            string s;
            if (!getline(cin, s) || !s\&.length())
                return 0;
            cout << \(dq\&Thank you for: \(dq\& << s << endl;
        }
    }
}
catch (Exception const &e)
{
    cout << e\&.what() << \(cq\&\en\(cq\&;
    return 1;
}
    
.fi 

.PP 
.SH "FILES"
\fIbobcat/selector\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBselect\fP(2)
.PP 
.SH "BUGS"
None reported
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP