chiark / gitweb /
Typo fixes.
[mLib] / man / sel.3
CommitLineData
b6b9d458 1.\" -*-nroff-*-
08da152e 2.TH sel 3 "22 May 1999" mLib
b6b9d458 3.SH NAME
4sel \- low level interface for waiting for I/O
08da152e 5.\" @sel_init
6.\" @sel_initfile
7.\" @sel_addfile
1101f87a 8.\" @sel_force
08da152e 9.\" @sel_rmfile
10.\" @sel_addtimer
11.\" @sel_rmtimer
b78d1e6d 12.\" @sel_addhook
13.\" @sel_rmhook
14.\" @sel_fdmerge
08da152e 15.\" @sel_select
b6b9d458 16.SH SYNOPSIS
17.nf
18.B "#include <mLib/sel.h>"
19
20.BI "void sel_init(sel_state *" s );
21
22.BI "void sel_initfile(sel_state *" s ", sel_file *" f ,
23.BI " int " fd ", unsigned " mode ,
24.BI " void (*" func ")(int " fd ", unsigned " mode ", void *" p ),
25.BI " void *" p );
26.BI "void sel_addfile(sel_file *" f );
1101f87a 27.BI "void sel_force(sel_file *" f );
b6b9d458 28.BI "void sel_rmfile(sel_file *" f );
29
30.BI "void sel_addtimer(sel_state *" s ", sel_timer *" t ,
31.BI " struct timeval *" tv ,
32.BI " void (*" func ")(struct timeval *" tv ", void *" p ),
33.BI "void sel_rmtimer(sel_timer *" t );
34
b78d1e6d 35.BI "void sel_addhook(sel_state *" s ", sel_hook *" h ,
36.BI " sel_hookfn " before ", sel_hookfn " after ,
37.BI " void *" p );
38.BI "void sel_rmhook(sel_hook *" h );
39
40.BI "int sel_fdmerge(fd_set *" dest ", fd_set *" fd ", int " maxfd );
41
b6b9d458 42.BI "int sel_select(sel_state *" s );
43.fi
44.SH "OVERVIEW"
45The
46.B sel
47subsystem provides a structured way of handling I/O in a non-blocking
48event-driven sort of a way, for single-threaded programs. (Although
49there's no reason at all why multithreaded programs shouldn't use
50.BR sel ,
51it's much less useful.)
52.PP
53The
54.B sel
55subsystem does no memory allocation, and has no static state. All
56of its data is stored in structures allocated by the caller. I'll
57explain how this fits in nicely with typical calling sequences below.
58.PP
59Although all the data structures are exposed in the header file, you
60should consider
61.BR sel 's
62data structures to be opaque except where described here, and not fiddle
63around inside them. Some things may become more sophisticated later.
64.SH "IMPORTANT CONCEPTS"
65The system is based around two concepts:
66.I multiplexors
67and
68.IR selectors .
69.PP
70A
71.I selector
72is interested in some sort of I/O event, which might be something like
73`my socket has become readable', or `the time is now half past three on
74the third of June 2013'. It has a handler function attached to it,
75which is called when the appropriate event occurs. Some events happen
76once only ever; some events happen over and over again. For example, a
77socket might become readable many times, but it's only half-past three
78on the third of June 2013 once.
79.PP
80When a selector is initialized, the caller describes the event the
81selector is interested in, and specifies which function should handle
82the event. Also, it must specify an arbitrary pointer which is passed
83to the handler function when the event occurs. This is typically some
84sort of pointer to instance data of some kind, providing more
85information about the event (`it's
86.I this
87socket that's become readable'), or what to do about it.
88.PP
89A multiplexor gathers information about who's interested in what. It
90maintains lists of selectors. Selectors must be added to a
91mulitplexor before the events they're interested in are actually watched
92for. Selectors can be removed again when their events aren't
93interesting any more. Apart from adding and removing selectors, you can
94.I select
95on a multiplexor. This waits for something interesting to happen and
96then fires off all the selectors which have events waiting for them.
97.PP
98You can have lots of multiplexors in your program if you like. You can
99only ask for events from one of them at a time, though.
100.PP
101There are currently two types of selector understood by the low-level
102.B sel
103system: file selectors and timer selectors. These two types of
104selectors react to corresponding different types of events. A file
105event indicates that a file is now ready for reading or writing. A
106timer event indicates that a particular time has now passed (useful for
107implementing timeouts). More sophisticated selectors can be constructed
108using
109.BR sel 's
110interface. For examples, see
08da152e 111.BR selbuf (3)
b6b9d458 112and
08da152e 113.BR conn (3).
b6b9d458 114.SH "PROGRAMMING INTERFACE"
1101f87a 115.SS "Multiplexors"
b6b9d458 116A multiplexor is represented using the type
117.B sel_state
118defined in the
119.B <mLib/sel.h>
120header file. Before use, a
121.B sel_state
122must be initialized, by passing it to the
123.B sel_init
124function. The header file talks about `state blocks' a lot \- that's
125because it was written before I thought the word `multiplexor' was
126nicer.
127.PP
128File selectors are represented by the type
129.BR sel_file .
130The interface provides three operations on file selectors:
131initialization, addition to multiplexor, and removal from a
132multiplexor. It's convenient to separate addition and removal from
133initialization because file selectors often get added and removed many
134times over during their lifetimes.
1101f87a 135.SS "File selectors"
b6b9d458 136A file selector is initialized by the
137.B sel_initfile
138function. This requires a large number of arguments:
139.TP
b78d1e6d 140.BI "sel_state *" s
b6b9d458 141A pointer to the multiplexor with which the file selector will be
142associated. This is stored in the selector so that the multiplexor
143argument can be omitted from later calls.
144.TP
b78d1e6d 145.BI "sel_file *" f
b6b9d458 146Pointer to the file selector object to be initialized.
147.TP
b78d1e6d 148.BI "int " fd
b6b9d458 149The file descriptor which the selector is meant to watch.
150.TP
b78d1e6d 151.BI "unsigned " mode
b6b9d458 152A constant describing which condition the selector is interested in.
153This must be one of the
154.B SEL_
155constants described below.
156.TP
b78d1e6d 157.BI "void (*" func ")(int " fd ", unsigned " mode ", void *" p );
b6b9d458 158The handler function which is called when the appropriate condition
159occurs on the file. This function's interface is described in more
160detail below.
161.TP
b78d1e6d 162.BI "void *" p
b6b9d458 163An arbitrary pointer argument passed to
164.I func
165when it's called. Beyond this, no meaning is attached to the value of
166the pointer. If you don't care about it, just leave it as null.
167.PP
168The mode argument is one of the following constants:
169.TP
170.B SEL_READ
171Raise an event when the file is ready to be read from.
172.TP
173.B SEL_WRITE
174Raise an event when the file is ready to be written to.
175.TP
176.B SEL_EXC
177Raise an event when the file has an `exceptional condition'.
178.PP
179The constant
180.B SEL_MODES
181contains the number of possible file modes. This is useful internally
182for allocating arrays of the right size.
183.PP
184The functions
185.B sel_addfile
186and
187.B sel_rmfile
188perform the addition and removal operations on file selectors. They are
189passed only the actual selector object, since the selector already knows
190which multiplexor it's associated with. A newly initialized file
191selector is not added to its multiplexor: this must be done explicitly.
192.PP
193The handler function for a file multiplexor is passed three arguments:
d2a91066 194the file descriptor for the file, a mode argument which describes the
b6b9d458 195file's new condition, and the pointer argument set up at initialization
196time.
197.PP
1101f87a 198The function
199.B sel_force
200will sometimes be useful while a
201.B sel_select
202call (see below) is in progress. It marks a file selector as being
203ready even if it's not really. This is most useful when dynamically
204adding a write selector: it's likely that the write will succeed
205immediately, so it's worth trying. This will only work properly if
206the write is non-blocking.
207.PP
b6b9d458 208The member
209.B fd
210of the
211.B sel_file
212structure is exported. It contains the file descriptor in which the
213selector is interested. You may not modify this value, but it's useful
214to be able to read it out \- it saves having to keep a copy.
1101f87a 215.SS "Timer selectors"
b6b9d458 216Timer selectors are simpler. There are only two operations provided on
217timer selectors: addition and removal. Initialization is performed as
218part of the addition operation.
219.PP
220A timer selector is represented by an object of time
221.BR sel_timer .
222.PP
223The function
224.B sel_addtimer
225requires lots of arguments:
226.TP
b78d1e6d 227.BI "sel_state *" s
b6b9d458 228Pointer to the multiplexor to which the selector is to be added.
229.TP
b78d1e6d 230.BI "sel_timer *" t
b6b9d458 231Pointer to the timer selector object being initialized and added.
232.TP
b78d1e6d 233.BI "struct timeval " tv
234When the selector should raise its event. This is an
b6b9d458 235.I absolute
236time, not a relative time as required by the traditional
237.BR select (2)
238and
239.BR poll (2)
240system calls.
241.TP
b78d1e6d 242.BI "void (*" func ")(struct timeval *" tv ", void *" p )
b6b9d458 243A handler function to be called when the event occurs. The function is
244passed the
245.I current
246time, and the arbitrary pointer passed to
247.B sel_addtimer
248as the
249.I p
250argument.
251.TP
b78d1e6d 252.BI "void *" p
b6b9d458 253A pointer passed to
254.I func
255when the timer event occurs. Beyond this, the value of the pointer is
256not inspected.
257.PP
258The function
259.B sel_rmtimer
260removes a timer selector. It is passed only the selector object.
261.PP
262Note that timer events are a one-shot thing. Once they've happened, the
263timer selector is removed and the event can't happen again. This is
264normally what you want. Removing a timer is only useful (or safe!)
265before the timer event has been sent.
1101f87a 266.SS "Performing I/O"
b6b9d458 267Finally, the function
268.B sel_select
269is passed a multiplexor object. It waits for something interesting to
270happen, informs the appropriate selector handlers, and returns. If
271everything went according to plan,
272.B sel_select
273returns zero. Otherwise it returns -1, and the global variable
274.B errno
275is set appropriately.
1101f87a 276.SS "Hook functions"
b78d1e6d 277In order to interface other I/O multiplexing systems to this one, it's
278possible to register
279.I hook
280functions which are called before and after each
281.BR select (2)
282system call.
283.PP
284The function
285.B sel_addhook
286registers a pair of hook functions. It is passed the pointer to the
287multiplexor which is being hooked, the address of a
288.B sel_hook
289structure which will be used to record the hook information, the two
290hook functions (either of which may be a null pointer, signifying no
291action to be taken), and a pointer argument to be passed to the hook
292functions.
293.PP
294The function
295.B sel_rmhook
296removes a pair of hooks given the address of the
297.B sel_hook
298structure which recorded their registration.
299.PP
300A
301.I "hook function"
302is passed three arguments:
303.TP
304.BI "sel_state *" s
305A pointer to the multiplexor block. This probably isn't very useful,
306actually.
307.TP
308.BI "sel_args *" a
309A pointer to a block containing proposed arguments for, or results from,
310.BR select (2).
311The format of this block is described below.
312.TP
313.BI "void *" p
314A pointer argument set up in the call to
315.B sel_addhook
316to provide the hook function with some context.
317.PP
318The argument block contains the following members:
319.TP
320.B "int maxfd"
321One greater than the highest-numbered file descriptor to be examined.
322This may need to be modified if the file descriptor sets are altered.
323.TP
324.B "fd_set fd[SEL_MODES]"
325A file descriptor set for each of
326.BR SEL_READ ,
327.B SEL_WRITE
328and
329.BR SEL_EXC .
330Before the
331.B select
332call, these may be modified to register an interest in other file
333descriptors. Afterwards, they may be examined to decide which file
334descriptors are active.
335.TP
336.B "struct timeval tv, *tvp"
337Before the
338.B select
339call, these specify the time after which to return even if no files are
340active. If
341.B tvp
342is null, there is no timeout, and
343.B select
344should wait forever if necessary. Otherwise
345.B tvp
346should contain the address of
347.BR tv ,
348and
349.B tv
350should contain the timeout. After the
351.B select
352call, the contents of
353.B tv
354are undefined.
355.TP
356.B "struct timeval now"
357Before the
358.B select
359call, contains the current time. After the call, this will have been
360updated to reflect the new current time only if there was a timeout
361set before the call.
362.PP
363Hook functions may find the call
364.B sel_fdmerge
365useful. Given two file descriptor sets
366.I dest
367and
368.IR fd ,
369and a possibly overestimated highest file descriptor in
370.IR fd ,
371the function sets in
372.I dest
373all of the descriptors set in
374.I fd
375and returns an accurate file descriptor count as its result.
b6b9d458 376.SH "OTHER NOTES"
377Although the naming seems to suggest that this is all
378based around the BSD-ish
379.BR select (2)
380system call (and indeed it is), the interface is actually a good deal
381more general than that. An implementation which worked off System V-ish
382.BR poll (2)
b78d1e6d 383instead would be possible to make, and would look just the same from the
384outside. Some work would be needed to make the hook functions work,
385though.
08da152e 386.SH "SEE ALSO"
387.BR select (2),
388.BR poll (2),
1101f87a 389.BR conn (3),
390.BR selbuf (3),
08da152e 391.BR mLib (3).
b6b9d458 392.SH AUTHOR
393Mark Wooding, <mdw@nsict.org>