2 .TH sel 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
4 sel \- low level interface for waiting for I/O
18 .B "#include <mLib/sel.h>"
21 .B "\h'4n'SEL_READ = ...,"
22 .B "\h'4n'SEL_WRITE = ...,"
23 .B "\h'4n'SEL_EXC = ...,"
24 .B "\h'4n'SEL_MODES = ..."
27 .B "typedef struct { ...\& } sel_state;"
28 .B "typedef struct { ...\& } sel_timer;"
29 .B "typedef struct { ...\& } sel_hook;"
38 .B "\h'4n'fd_set fd[SEL_MODES];"
39 .B "\h'4n'struct timeval tv, *tvp;"
40 .B "\h'4n'struct timeval now;"
43 .BI "typedef void (*sel_hookfn)(sel_state *" s ", sel_args *" a ", void *" p );
45 .BI "void sel_init(sel_state *" s );
47 .ds mT \fBvoid sel_initfile(
48 .BI "\*(mTsel_state *" s ", sel_file *" f ,
49 .BI "\h'\w'\*(mT'u'int " fd ", unsigned " mode ,
50 .BI "\h'\w'\*(mT'u'void (*" func ")(int " fd ", unsigned " mode ", void *" p ),
51 .BI "\h'\w'\*(mT'u'void *" p );
52 .BI "void sel_addfile(sel_file *" f );
53 .BI "void sel_force(sel_file *" f );
54 .BI "void sel_rmfile(sel_file *" f );
56 .ds mT \fBvoid sel_addtimer(
57 .BI "\*(mTsel_state *" s ", sel_timer *" t ,
58 .BI "\h'\w'\*(mT'u'struct timeval *" tv ,
59 .BI "\h'\w'\*(mT'u'void (*" func ")(struct timeval *" tv ", void *" p ),
60 .BI "\h'\w'\*(mT'u'void *" p );
61 .BI "void sel_rmtimer(sel_timer *" t );
63 .ds mT \fBvoid sel_addhook(
64 .BI "\*(mTsel_state *" s ", sel_hook *" h ,
65 .BI "\h'\w'\*(mT'u'sel_hookfn " before ", sel_hookfn " after ,
66 .BI "\h'\w'\*(mT'u'void *" p );
67 .BI "void sel_rmhook(sel_hook *" h );
69 .BI "int sel_fdmerge(fd_set *" dest ", fd_set *" fd ", int " maxfd );
71 .BI "int sel_select(sel_state *" s );
76 subsystem provides a structured way of handling I/O in a non-blocking
77 event-driven sort of a way, for single-threaded programs. (Although
78 there's no reason at all why multithreaded programs shouldn't use
80 it's much less useful.)
84 subsystem does no memory allocation, and has no static state. All
85 of its data is stored in structures allocated by the caller. I'll
86 explain how this fits in nicely with typical calling sequences below.
88 Although all the data structures are exposed in the header file, you
91 data structures to be opaque except where described here, and not fiddle
92 around inside them. Some things may become more sophisticated later.
93 .SH "IMPORTANT CONCEPTS"
94 The system is based around two concepts:
101 is interested in some sort of I/O event, which might be something like
102 `my socket has become readable', or `the time is now half past three on
103 the third of June 2013'. It has a handler function attached to it,
104 which is called when the appropriate event occurs. Some events happen
105 once only ever; some events happen over and over again. For example, a
106 socket might become readable many times, but it's only half-past three
107 on the third of June 2013 once.
109 When a selector is initialized, the caller describes the event the
110 selector is interested in, and specifies which function should handle
111 the event. Also, it must specify an arbitrary pointer which is passed
112 to the handler function when the event occurs. This is typically some
113 sort of pointer to instance data of some kind, providing more
114 information about the event (`it's
116 socket that's become readable'), or what to do about it.
118 A multiplexor gathers information about who's interested in what. It
119 maintains lists of selectors. Selectors must be added to a
120 mulitplexor before the events they're interested in are actually watched
121 for. Selectors can be removed again when their events aren't
122 interesting any more. Apart from adding and removing selectors, you can
124 on a multiplexor. This waits for something interesting to happen and
125 then fires off all the selectors which have events waiting for them.
127 You can have lots of multiplexors in your program if you like. You can
128 only ask for events from one of them at a time, though.
130 There are currently two types of selector understood by the low-level
132 system: file selectors and timer selectors. These two types of
133 selectors react to corresponding different types of events. A file
134 event indicates that a file is now ready for reading or writing. A
135 timer event indicates that a particular time has now passed (useful for
136 implementing timeouts). More sophisticated selectors can be constructed
139 interface. For examples, see
143 .SH "PROGRAMMING INTERFACE"
145 A multiplexor is represented using the type
149 header file. Before use, a
151 must be initialized, by passing it to the
153 function. The header file talks about `state blocks' a lot \- that's
154 because it was written before I thought the word `multiplexor' was
157 File selectors are represented by the type
159 The interface provides three operations on file selectors:
160 initialization, addition to multiplexor, and removal from a
161 multiplexor. It's convenient to separate addition and removal from
162 initialization because file selectors often get added and removed many
163 times over during their lifetimes.
165 A file selector is initialized by the
167 function. This requires a large number of arguments:
170 A pointer to the multiplexor with which the file selector will be
171 associated. This is stored in the selector so that the multiplexor
172 argument can be omitted from later calls.
175 Pointer to the file selector object to be initialized.
178 The file descriptor which the selector is meant to watch.
181 A constant describing which condition the selector is interested in.
182 This must be one of the
184 constants described below.
186 .BI "void (*" func ")(int " fd ", unsigned " mode ", void *" p );
187 The handler function which is called when the appropriate condition
188 occurs on the file. This function's interface is described in more
192 An arbitrary pointer argument passed to
194 when it's called. Beyond this, no meaning is attached to the value of
195 the pointer. If you don't care about it, just leave it as null.
197 The mode argument is one of the following constants:
200 Raise an event when the file is ready to be read from.
203 Raise an event when the file is ready to be written to.
206 Raise an event when the file has an `exceptional condition'.
210 contains the number of possible file modes. This is useful internally
211 for allocating arrays of the right size.
217 perform the addition and removal operations on file selectors. They are
218 passed only the actual selector object, since the selector already knows
219 which multiplexor it's associated with. A newly initialized file
220 selector is not added to its multiplexor: this must be done explicitly.
222 The handler function for a file multiplexor is passed three arguments:
223 the file descriptor for the file, a mode argument which describes the
224 file's new condition, and the pointer argument set up at initialization
229 will sometimes be useful while a
231 call (see below) is in progress. It marks a file selector as being
232 ready even if it's not really. This is most useful when dynamically
233 adding a write selector: it's likely that the write will succeed
234 immediately, so it's worth trying. This will only work properly if
235 the write is non-blocking.
241 structure is exported. It contains the file descriptor in which the
242 selector is interested. You may not modify this value, but it's useful
243 to be able to read it out \- it saves having to keep a copy.
244 .SS "Timer selectors"
245 Timer selectors are simpler. There are only two operations provided on
246 timer selectors: addition and removal. Initialization is performed as
247 part of the addition operation.
249 A timer selector is represented by an object of time
254 requires lots of arguments:
257 Pointer to the multiplexor to which the selector is to be added.
260 Pointer to the timer selector object being initialized and added.
262 .BI "struct timeval " tv
263 When the selector should raise its event. This is an
265 time, not a relative time as required by the traditional
271 .BI "void (*" func ")(struct timeval *" tv ", void *" p )
272 A handler function to be called when the event occurs. The function is
275 time, and the arbitrary pointer passed to
284 when the timer event occurs. Beyond this, the value of the pointer is
289 removes a timer selector. It is passed only the selector object.
291 Note that timer events are a one-shot thing. Once they've happened, the
292 timer selector is removed and the event can't happen again. This is
293 normally what you want. Removing a timer is only useful (or safe!)
294 before the timer event has been sent.
296 Finally, the function
298 is passed a multiplexor object. It waits for something interesting to
299 happen, informs the appropriate selector handlers, and returns. If
300 everything went according to plan,
302 returns zero. Otherwise it returns \-1, and the global variable
304 is set appropriately.
306 In order to interface other I/O multiplexing systems to this one, it's
309 functions which are called before and after each
315 registers a pair of hook functions. It is passed the pointer to the
316 multiplexor which is being hooked, the address of a
318 structure which will be used to record the hook information, the two
319 hook functions (either of which may be a null pointer, signifying no
320 action to be taken), and a pointer argument to be passed to the hook
325 removes a pair of hooks given the address of the
327 structure which recorded their registration.
331 is passed three arguments:
334 A pointer to the multiplexor block. This probably isn't very useful,
338 A pointer to a block containing proposed arguments for, or results from,
340 The format of this block is described below.
343 A pointer argument set up in the call to
345 to provide the hook function with some context.
347 The argument block contains the following members:
350 One greater than the highest-numbered file descriptor to be examined.
351 This may need to be modified if the file descriptor sets are altered.
353 .B "fd_set fd[SEL_MODES]"
354 A file descriptor set for each of
361 call, these may be modified to register an interest in other file
362 descriptors. Afterwards, they may be examined to decide which file
363 descriptors are active.
365 .B "struct timeval tv, *tvp"
368 call, these specify the time after which to return even if no files are
371 is null, there is no timeout, and
373 should wait forever if necessary. Otherwise
375 should contain the address of
379 should contain the timeout. After the
381 call, the contents of
385 .B "struct timeval now"
388 call, contains the current time. After the call, this will have been
389 updated to reflect the new current time only if there was a timeout
392 Hook functions may find the call
394 useful. Given two file descriptor sets
398 and a possibly overestimated highest file descriptor in
402 all of the descriptors set in
404 and returns an accurate file descriptor count as its result.
406 Although the naming seems to suggest that this is all
407 based around the BSD-ish
409 system call (and indeed it is), the interface is actually a good deal
410 more general than that. An implementation which worked off System V-ish
412 instead would be possible to make, and would look just the same from the
413 outside. Some work would be needed to make the hook functions work,
422 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob