Document SELECT/SELECT!.

This commit is contained in:
sperber 2002-11-13 12:21:33 +00:00
parent 883117ae06
commit 3148ef6a41
1 changed files with 59 additions and 41 deletions

View File

@ -776,48 +776,66 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
\defun {select }{rvec wvec evec [timeout]}{[rvec' wvec' evec']}
\defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]}
\begin{desc}
\emph{These two procedures have been de-released for version 0.6.
They will come back in a later verison of Scsh.}
% The \ex{select} procedure allows a process to block and wait for
% events on multiple I/O channels. The \var{rvec} and \var{evec}
% arguments are vectors of input ports and integer file descriptors;
% \var{wvec} is a vector of output ports and integer file
% descriptors. The procedure returns three vectors whose elements
% are subsets of the corresponding arguments. Every element of
% \var{rvec'} is ready for input; every element of \var{wvec'} is
% ready for output; every element of \var{evec'} has an exceptional
% condition pending.
The \ex{select} procedure allows a process to block and wait for
events on multiple I/O channels. The \var{rvec} and \var{evec}
arguments are vectors of input ports and integer file descriptors;
\var{wvec} is a vector of output ports and integer file
descriptors. The procedure returns three vectors whose elements
are subsets of the corresponding arguments. Every element of
\var{rvec'} is ready for input; every element of \var{wvec'} is
ready for output; every element of \var{evec'} has an exceptional
condition pending.
The \ex{select} call will block until at least one of the I/O
channels passed to it is ready for operation. For an input port
this means that it either has data sitting its buffer or that the
underlying file descriptor has data waiting. For an output port
this means that it either has space available in the associated
buffer or that the underlying file descriptor can accept output.
For file descriptors, no buffers are checked, even if they have
associated ports.
% The \ex{select} call will block until at least one of the I/O
% channels passed to it is ready for operation. The \var{timeout}
% value can be used to force the call to time-out after a given
% number of seconds. It defaults to the special value \ex{\#f},
% meaning wait indefinitely. A zero value can be used to poll the
% I/O channels.
% If an I/O channel appears more than once in a given
% vector---perhaps occuring once as a Scheme port, and once as the
% port's underlying integer file descriptor---only one of these two
% references may appear in the returned vector. Buffered I/O ports
% are handled specially---if an input port's buffer is not empty, or
% an output port's buffer is not yet full, then these ports are
% immediately considered eligible for I/O without using the actual,
% primitive \ex{select} system call to check the underlying file
% descriptor. This works pretty well for buffered input ports, but
% is a little problematic for buffered output ports.
% The \ex{select!} procedure is similar, but indicates the subset of
% active I/O channels by side-effecting the argument vectors.
% Non-active I/O channels in the argument vectors are overwritten
% with {\sharpf} values. The call returns the number of active
% elements remaining in each vector. As a convenience, the vectors
% passed in to \ex{select!} are allowed to contain {\sharpf} values
% as well as integers and ports.
% \remark{I have found the \ex{select!} interface to be the more
% useful of the two. After the system call, it allows you to check
% a specific I/O channel in constant time.}
The \var{timeout} value can be used to force the call to time-out
after a given number of seconds. It defaults to the special value
\ex{\#f}, meaning wait indefinitely. A zero value can be used to
poll the I/O channels.
If an I/O channel appears more than once in a given
vector---perhaps occuring once as a Scheme port, and once as the
port's underlying integer file descriptor---only one of these two
references may appear in the returned vector. Buffered I/O ports
are handled specially---if an input port's buffer is not empty, or
an output port's buffer is not yet full, then these ports are
immediately considered eligible for I/O without using the actual,
primitive \ex{select} system call to check the underlying file
descriptor. This works pretty well for buffered input ports, but
is a little problematic for buffered output ports.
The \ex{select!} procedure is similar, but indicates the subset of
active I/O channels by side-effecting the argument vectors.
Non-active I/O channels in the argument vectors are overwritten
with {\sharpf} values. The call returns the number of active
elements remaining in each vector. As a convenience, the vectors
passed in to \ex{select!} are allowed to contain {\sharpf} values
as well as integers and ports.
\remark{\texttt{Select} and \texttt{select!} do not
call their POSIX counterparts directly---there is a POSIX
\texttt{select} sitting at the very heart of the Scheme 48/scsh
I/O system, so \emph{all} multiplexed I/O is really
\texttt{select}-based. Therefore, you cannot expect a
performance increase from writing a single-threaded program
using \texttt{select} and \texttt{select!} instead of writing a
multi-threaded program where each thread handles one I/O
connection.
The moral of this story is that \texttt{select} and
\texttt{select!} make sense in only two situations: legacy code
written for an older version of scsh, and programs which make
inherent use of \texttt{select}/\texttt{select!} which do not
benefit from multiple threads. Examples are network clients
that send requests to multiple alternate servers and discard all
but one of them.}
\end{desc}
\begin{defundescx}{write-string}{string [fd/port start end]}\undefined