--- /dev/null
+.\" -*-nroff-*-
+.TH sel 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+sel \- low level interface for waiting for I/O
+.\" @sel_init
+.\" @sel_initfile
+.\" @sel_addfile
+.\" @sel_force
+.\" @sel_rmfile
+.\" @sel_addtimer
+.\" @sel_rmtimer
+.\" @sel_addhook
+.\" @sel_rmhook
+.\" @sel_fdmerge
+.\" @sel_select
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/sel.h>"
+
+.BI "void sel_init(sel_state *" s );
+
+.BI "void sel_initfile(sel_state *" s ", sel_file *" f ,
+.BI " int " fd ", unsigned " mode ,
+.BI " void (*" func ")(int " fd ", unsigned " mode ", void *" p ),
+.BI " void *" p );
+.BI "void sel_addfile(sel_file *" f );
+.BI "void sel_force(sel_file *" f );
+.BI "void sel_rmfile(sel_file *" f );
+
+.BI "void sel_addtimer(sel_state *" s ", sel_timer *" t ,
+.BI " struct timeval *" tv ,
+.BI " void (*" func ")(struct timeval *" tv ", void *" p ),
+.BI " void *" p );
+.BI "void sel_rmtimer(sel_timer *" t );
+
+.BI "void sel_addhook(sel_state *" s ", sel_hook *" h ,
+.BI " sel_hookfn " before ", sel_hookfn " after ,
+.BI " void *" p );
+.BI "void sel_rmhook(sel_hook *" h );
+
+.BI "int sel_fdmerge(fd_set *" dest ", fd_set *" fd ", int " maxfd );
+
+.BI "int sel_select(sel_state *" s );
+.fi
+.SH "OVERVIEW"
+The
+.B sel
+subsystem provides a structured way of handling I/O in a non-blocking
+event-driven sort of a way, for single-threaded programs. (Although
+there's no reason at all why multithreaded programs shouldn't use
+.BR sel ,
+it's much less useful.)
+.PP
+The
+.B sel
+subsystem does no memory allocation, and has no static state. All
+of its data is stored in structures allocated by the caller. I'll
+explain how this fits in nicely with typical calling sequences below.
+.PP
+Although all the data structures are exposed in the header file, you
+should consider
+.BR sel 's
+data structures to be opaque except where described here, and not fiddle
+around inside them. Some things may become more sophisticated later.
+.SH "IMPORTANT CONCEPTS"
+The system is based around two concepts:
+.I multiplexors
+and
+.IR selectors .
+.PP
+A
+.I selector
+is interested in some sort of I/O event, which might be something like
+`my socket has become readable', or `the time is now half past three on
+the third of June 2013'. It has a handler function attached to it,
+which is called when the appropriate event occurs. Some events happen
+once only ever; some events happen over and over again. For example, a
+socket might become readable many times, but it's only half-past three
+on the third of June 2013 once.
+.PP
+When a selector is initialized, the caller describes the event the
+selector is interested in, and specifies which function should handle
+the event. Also, it must specify an arbitrary pointer which is passed
+to the handler function when the event occurs. This is typically some
+sort of pointer to instance data of some kind, providing more
+information about the event (`it's
+.I this
+socket that's become readable'), or what to do about it.
+.PP
+A multiplexor gathers information about who's interested in what. It
+maintains lists of selectors. Selectors must be added to a
+mulitplexor before the events they're interested in are actually watched
+for. Selectors can be removed again when their events aren't
+interesting any more. Apart from adding and removing selectors, you can
+.I select
+on a multiplexor. This waits for something interesting to happen and
+then fires off all the selectors which have events waiting for them.
+.PP
+You can have lots of multiplexors in your program if you like. You can
+only ask for events from one of them at a time, though.
+.PP
+There are currently two types of selector understood by the low-level
+.B sel
+system: file selectors and timer selectors. These two types of
+selectors react to corresponding different types of events. A file
+event indicates that a file is now ready for reading or writing. A
+timer event indicates that a particular time has now passed (useful for
+implementing timeouts). More sophisticated selectors can be constructed
+using
+.BR sel 's
+interface. For examples, see
+.BR selbuf (3)
+and
+.BR conn (3).
+.SH "PROGRAMMING INTERFACE"
+.SS "Multiplexors"
+A multiplexor is represented using the type
+.B sel_state
+defined in the
+.B <mLib/sel.h>
+header file. Before use, a
+.B sel_state
+must be initialized, by passing it to the
+.B sel_init
+function. The header file talks about `state blocks' a lot \- that's
+because it was written before I thought the word `multiplexor' was
+nicer.
+.PP
+File selectors are represented by the type
+.BR sel_file .
+The interface provides three operations on file selectors:
+initialization, addition to multiplexor, and removal from a
+multiplexor. It's convenient to separate addition and removal from
+initialization because file selectors often get added and removed many
+times over during their lifetimes.
+.SS "File selectors"
+A file selector is initialized by the
+.B sel_initfile
+function. This requires a large number of arguments:
+.TP
+.BI "sel_state *" s
+A pointer to the multiplexor with which the file selector will be
+associated. This is stored in the selector so that the multiplexor
+argument can be omitted from later calls.
+.TP
+.BI "sel_file *" f
+Pointer to the file selector object to be initialized.
+.TP
+.BI "int " fd
+The file descriptor which the selector is meant to watch.
+.TP
+.BI "unsigned " mode
+A constant describing which condition the selector is interested in.
+This must be one of the
+.B SEL_
+constants described below.
+.TP
+.BI "void (*" func ")(int " fd ", unsigned " mode ", void *" p );
+The handler function which is called when the appropriate condition
+occurs on the file. This function's interface is described in more
+detail below.
+.TP
+.BI "void *" p
+An arbitrary pointer argument passed to
+.I func
+when it's called. Beyond this, no meaning is attached to the value of
+the pointer. If you don't care about it, just leave it as null.
+.PP
+The mode argument is one of the following constants:
+.TP
+.B SEL_READ
+Raise an event when the file is ready to be read from.
+.TP
+.B SEL_WRITE
+Raise an event when the file is ready to be written to.
+.TP
+.B SEL_EXC
+Raise an event when the file has an `exceptional condition'.
+.PP
+The constant
+.B SEL_MODES
+contains the number of possible file modes. This is useful internally
+for allocating arrays of the right size.
+.PP
+The functions
+.B sel_addfile
+and
+.B sel_rmfile
+perform the addition and removal operations on file selectors. They are
+passed only the actual selector object, since the selector already knows
+which multiplexor it's associated with. A newly initialized file
+selector is not added to its multiplexor: this must be done explicitly.
+.PP
+The handler function for a file multiplexor is passed three arguments:
+the file descriptor for the file, a mode argument which describes the
+file's new condition, and the pointer argument set up at initialization
+time.
+.PP
+The function
+.B sel_force
+will sometimes be useful while a
+.B sel_select
+call (see below) is in progress. It marks a file selector as being
+ready even if it's not really. This is most useful when dynamically
+adding a write selector: it's likely that the write will succeed
+immediately, so it's worth trying. This will only work properly if
+the write is non-blocking.
+.PP
+The member
+.B fd
+of the
+.B sel_file
+structure is exported. It contains the file descriptor in which the
+selector is interested. You may not modify this value, but it's useful
+to be able to read it out \- it saves having to keep a copy.
+.SS "Timer selectors"
+Timer selectors are simpler. There are only two operations provided on
+timer selectors: addition and removal. Initialization is performed as
+part of the addition operation.
+.PP
+A timer selector is represented by an object of time
+.BR sel_timer .
+.PP
+The function
+.B sel_addtimer
+requires lots of arguments:
+.TP
+.BI "sel_state *" s
+Pointer to the multiplexor to which the selector is to be added.
+.TP
+.BI "sel_timer *" t
+Pointer to the timer selector object being initialized and added.
+.TP
+.BI "struct timeval " tv
+When the selector should raise its event. This is an
+.I absolute
+time, not a relative time as required by the traditional
+.BR select (2)
+and
+.BR poll (2)
+system calls.
+.TP
+.BI "void (*" func ")(struct timeval *" tv ", void *" p )
+A handler function to be called when the event occurs. The function is
+passed the
+.I current
+time, and the arbitrary pointer passed to
+.B sel_addtimer
+as the
+.I p
+argument.
+.TP
+.BI "void *" p
+A pointer passed to
+.I func
+when the timer event occurs. Beyond this, the value of the pointer is
+not inspected.
+.PP
+The function
+.B sel_rmtimer
+removes a timer selector. It is passed only the selector object.
+.PP
+Note that timer events are a one-shot thing. Once they've happened, the
+timer selector is removed and the event can't happen again. This is
+normally what you want. Removing a timer is only useful (or safe!)
+before the timer event has been sent.
+.SS "Performing I/O"
+Finally, the function
+.B sel_select
+is passed a multiplexor object. It waits for something interesting to
+happen, informs the appropriate selector handlers, and returns. If
+everything went according to plan,
+.B sel_select
+returns zero. Otherwise it returns \-1, and the global variable
+.B errno
+is set appropriately.
+.SS "Hook functions"
+In order to interface other I/O multiplexing systems to this one, it's
+possible to register
+.I hook
+functions which are called before and after each
+.BR select (2)
+system call.
+.PP
+The function
+.B sel_addhook
+registers a pair of hook functions. It is passed the pointer to the
+multiplexor which is being hooked, the address of a
+.B sel_hook
+structure which will be used to record the hook information, the two
+hook functions (either of which may be a null pointer, signifying no
+action to be taken), and a pointer argument to be passed to the hook
+functions.
+.PP
+The function
+.B sel_rmhook
+removes a pair of hooks given the address of the
+.B sel_hook
+structure which recorded their registration.
+.PP
+A
+.I "hook function"
+is passed three arguments:
+.TP
+.BI "sel_state *" s
+A pointer to the multiplexor block. This probably isn't very useful,
+actually.
+.TP
+.BI "sel_args *" a
+A pointer to a block containing proposed arguments for, or results from,
+.BR select (2).
+The format of this block is described below.
+.TP
+.BI "void *" p
+A pointer argument set up in the call to
+.B sel_addhook
+to provide the hook function with some context.
+.PP
+The argument block contains the following members:
+.TP
+.B "int maxfd"
+One greater than the highest-numbered file descriptor to be examined.
+This may need to be modified if the file descriptor sets are altered.
+.TP
+.B "fd_set fd[SEL_MODES]"
+A file descriptor set for each of
+.BR SEL_READ ,
+.B SEL_WRITE
+and
+.BR SEL_EXC .
+Before the
+.B select
+call, these may be modified to register an interest in other file
+descriptors. Afterwards, they may be examined to decide which file
+descriptors are active.
+.TP
+.B "struct timeval tv, *tvp"
+Before the
+.B select
+call, these specify the time after which to return even if no files are
+active. If
+.B tvp
+is null, there is no timeout, and
+.B select
+should wait forever if necessary. Otherwise
+.B tvp
+should contain the address of
+.BR tv ,
+and
+.B tv
+should contain the timeout. After the
+.B select
+call, the contents of
+.B tv
+are undefined.
+.TP
+.B "struct timeval now"
+Before the
+.B select
+call, contains the current time. After the call, this will have been
+updated to reflect the new current time only if there was a timeout
+set before the call.
+.PP
+Hook functions may find the call
+.B sel_fdmerge
+useful. Given two file descriptor sets
+.I dest
+and
+.IR fd ,
+and a possibly overestimated highest file descriptor in
+.IR fd ,
+the function sets in
+.I dest
+all of the descriptors set in
+.I fd
+and returns an accurate file descriptor count as its result.
+.SH "OTHER NOTES"
+Although the naming seems to suggest that this is all
+based around the BSD-ish
+.BR select (2)
+system call (and indeed it is), the interface is actually a good deal
+more general than that. An implementation which worked off System V-ish
+.BR poll (2)
+instead would be possible to make, and would look just the same from the
+outside. Some work would be needed to make the hook functions work,
+though.
+.SH "SEE ALSO"
+.BR select (2),
+.BR poll (2),
+.BR conn (3),
+.BR selbuf (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff