2 .TH sel 3mLib "22 May 1999" mLib
4 sel \- low level interface for waiting for I/O
7 .B "#include <mLib/sel.h>"
9 .BI "void sel_init(sel_state *" s );
11 .BI "void sel_initfile(sel_state *" s ", sel_file *" f ,
12 .BI " int " fd ", unsigned " mode ,
13 .BI " void (*" func ")(int " fd ", unsigned " mode ", void *" p ),
15 .BI "void sel_addfile(sel_file *" f );
16 .BI "void sel_rmfile(sel_file *" f );
18 .BI "void sel_addtimer(sel_state *" s ", sel_timer *" t ,
19 .BI " struct timeval *" tv ,
20 .BI " void (*" func ")(struct timeval *" tv ", void *" p ),
21 .BI "void sel_rmtimer(sel_timer *" t );
23 .BI "int sel_select(sel_state *" s );
28 subsystem provides a structured way of handling I/O in a non-blocking
29 event-driven sort of a way, for single-threaded programs. (Although
30 there's no reason at all why multithreaded programs shouldn't use
32 it's much less useful.)
36 subsystem does no memory allocation, and has no static state. All
37 of its data is stored in structures allocated by the caller. I'll
38 explain how this fits in nicely with typical calling sequences below.
40 Although all the data structures are exposed in the header file, you
43 data structures to be opaque except where described here, and not fiddle
44 around inside them. Some things may become more sophisticated later.
45 .SH "IMPORTANT CONCEPTS"
46 The system is based around two concepts:
53 is interested in some sort of I/O event, which might be something like
54 `my socket has become readable', or `the time is now half past three on
55 the third of June 2013'. It has a handler function attached to it,
56 which is called when the appropriate event occurs. Some events happen
57 once only ever; some events happen over and over again. For example, a
58 socket might become readable many times, but it's only half-past three
59 on the third of June 2013 once.
61 When a selector is initialized, the caller describes the event the
62 selector is interested in, and specifies which function should handle
63 the event. Also, it must specify an arbitrary pointer which is passed
64 to the handler function when the event occurs. This is typically some
65 sort of pointer to instance data of some kind, providing more
66 information about the event (`it's
68 socket that's become readable'), or what to do about it.
70 A multiplexor gathers information about who's interested in what. It
71 maintains lists of selectors. Selectors must be added to a
72 mulitplexor before the events they're interested in are actually watched
73 for. Selectors can be removed again when their events aren't
74 interesting any more. Apart from adding and removing selectors, you can
76 on a multiplexor. This waits for something interesting to happen and
77 then fires off all the selectors which have events waiting for them.
79 You can have lots of multiplexors in your program if you like. You can
80 only ask for events from one of them at a time, though.
82 There are currently two types of selector understood by the low-level
84 system: file selectors and timer selectors. These two types of
85 selectors react to corresponding different types of events. A file
86 event indicates that a file is now ready for reading or writing. A
87 timer event indicates that a particular time has now passed (useful for
88 implementing timeouts). More sophisticated selectors can be constructed
91 interface. For examples, see
95 .SH "PROGRAMMING INTERFACE"
96 A multiplexor is represented using the type
100 header file. Before use, a
102 must be initialized, by passing it to the
104 function. The header file talks about `state blocks' a lot \- that's
105 because it was written before I thought the word `multiplexor' was
108 File selectors are represented by the type
110 The interface provides three operations on file selectors:
111 initialization, addition to multiplexor, and removal from a
112 multiplexor. It's convenient to separate addition and removal from
113 initialization because file selectors often get added and removed many
114 times over during their lifetimes.
116 A file selector is initialized by the
118 function. This requires a large number of arguments:
121 A pointer to the multiplexor with which the file selector will be
122 associated. This is stored in the selector so that the multiplexor
123 argument can be omitted from later calls.
126 Pointer to the file selector object to be initialized.
129 The file descriptor which the selector is meant to watch.
132 A constant describing which condition the selector is interested in.
133 This must be one of the
135 constants described below.
138 The handler function which is called when the appropriate condition
139 occurs on the file. This function's interface is described in more
143 An arbitrary pointer argument passed to
145 when it's called. Beyond this, no meaning is attached to the value of
146 the pointer. If you don't care about it, just leave it as null.
148 The mode argument is one of the following constants:
151 Raise an event when the file is ready to be read from.
154 Raise an event when the file is ready to be written to.
157 Raise an event when the file has an `exceptional condition'.
161 contains the number of possible file modes. This is useful internally
162 for allocating arrays of the right size.
168 perform the addition and removal operations on file selectors. They are
169 passed only the actual selector object, since the selector already knows
170 which multiplexor it's associated with. A newly initialized file
171 selector is not added to its multiplexor: this must be done explicitly.
173 The handler function for a file multiplexor is passed three arguments:
174 the file descriptor for the file, a mode argument which descibes the
175 file's new condition, and the pointer argument set up at initialization
182 structure is exported. It contains the file descriptor in which the
183 selector is interested. You may not modify this value, but it's useful
184 to be able to read it out \- it saves having to keep a copy.
186 Timer selectors are simpler. There are only two operations provided on
187 timer selectors: addition and removal. Initialization is performed as
188 part of the addition operation.
190 A timer selector is represented by an object of time
195 requires lots of arguments:
198 Pointer to the multiplexor to which the selector is to be added.
201 Pointer to the timer selector object being initialized and added.
206 object describing when the selector should raise its event. This is an
208 time, not a relative time as required by the traditional
215 A handler function to be called when the event occurs. The function is
218 time, and the arbitrary pointer passed to
227 when the timer event occurs. Beyond this, the value of the pointer is
232 removes a timer selector. It is passed only the selector object.
234 Note that timer events are a one-shot thing. Once they've happened, the
235 timer selector is removed and the event can't happen again. This is
236 normally what you want. Removing a timer is only useful (or safe!)
237 before the timer event has been sent.
239 Finally, the function
241 is passed a multiplexor object. It waits for something interesting to
242 happen, informs the appropriate selector handlers, and returns. If
243 everything went according to plan,
245 returns zero. Otherwise it returns -1, and the global variable
247 is set appropriately.
249 Although the naming seems to suggest that this is all
250 based around the BSD-ish
252 system call (and indeed it is), the interface is actually a good deal
253 more general than that. An implementation which worked off System V-ish
255 instead would be fairly trivial to make, and would look just the same
258 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob