1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
includefile(include/header)
COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Selector)(3bobcat)(_CurYrs_)(libbobcat1-dev__CurVers_-x.tar.gz)
(Timed Delays, Multiple File I/O)
manpagename(FBB::Selector)(Timed delays, Alarms and Multiple File I/O.)
manpagesynopsis()
bf(#include <bobcat/selector>)nl()
Linking option: tt(-lbobcat)
manpagedescription()
bf(FBB::Selector) objects are wrappers around the bf(select)(2) system
calls and allow timed delays, alarm functionality and/or multiple file I/O. It
requires the use of em(file descriptors), which are not an official part of
bf(C++). However, most operating systems offer em(file descriptors). Sockets
are well-known file descriptors.
includefile(include/namespace)
manpagesection(INHERITS FROM)
-
manpagesection(CONSTRUCTORS)
itemization(
itb(Selector())
This constructor initializes the object.
)
The copy constructor is available.
manpagesection(MEMBER FUNCTIONS)
itemization(
itb(void addExceptFd(int fd))
Adds a filedescriptor to the set of file descriptors that are
monitored for exceptions (note these are not bf(C++) exceptions. See tt(man 2
select) for details).
itb(void addReadFd(int fd))
Adds a filedescriptor to the set of file descriptors that are
monitored for reading.
itb(void addWriteFd(int fd))
Adds a filedescriptor to the set of file descriptors that are
monitored for writing.
itb(int exceptFd())
Returns -1 of no more file descriptors are
available in the em(exception) category. Otherwise the next available file
descriptor in the em(exception) category is returned. Returning from
tt(wait), this function can be called repeatedly until -1 is returned,
servicing each available filedescriptor in turn.
itb(void noAlarm())
This member prevents any timeout-alarm from occurring.
itb(int nReady())
Returns the number of available file descriptors. 0 is returned at a
timeout, -1: is returned when tt(select)(2) itself failed.
itb(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 tt(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 tt(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.
itb(void rmExceptFd(int fd))
Removes a filedescriptor from the set of file descriptors that are
monitored for exceptions (note these are not bf(C++) exceptions. See tt(man 2
select) for details).
itb(void rmReadFd(int fd))
Removes a filedescriptor from the set of file descriptors that are
monitored for reading.
itb(void rmWriteFd(int fd))
Removes a filedescriptor from the set of file descriptors that are
monitored for writing.
itb(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, tt(wait) will return with
tt(nReady) returning 0. The requested alarm time (tt(sec + usec / 1e+6)) may
not be negative and may not exceed tt(INT_MAX) or an tt(FBB::Errno) exception
(see tt(setAlarm)) will be thrown. A 0 alarm time specification
results in tt(wait) returning immediately. To switch off the alarm time use
tt(noAlarm).
itb(int wait())
This member should be called to wait for activities on the installed
file descriptors or timeout-period. The members tt(exceptFd, nReady,
readFd) and tt(writeFd) show their defined behaviors only after tt(wait)
has returned. It throws an tt(FBB::Errno) exception when bf(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 tt(wait)
may also return with an input file descriptor returned by tt(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.
itb(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 tt(wait), this function can be called repeatedly
until -1 is returned, servicing each available filedescriptor in turn.
)
manpagesection(EXAMPLE)
verb(
#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;
}
)
manpagefiles()
em(bobcat/selector) - defines the class interface
manpageseealso()
bf(bobcat)(7), bf(select)(2)
manpagebugs()
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 tt(wait) may decay to an empty set. If
tt(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 tt(wait).
Facilities to prevent tt(wait) from waiting indefinitely in this situation
will be added to tt(Selector) in a future Bobcat release.
includefile(include/trailer)
|
