Document SELECT/SELECT!.

doc/scsh-manual/syscalls.tex

@@ -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.
+    The \ex{select} procedure allows a process to block and wait for
-    They will come back in a later verison of Scsh.}
+    events on multiple I/O channels.  The \var{rvec} and \var{evec}
-
+    arguments are vectors of input ports and integer file descriptors;
-%    The \ex{select} procedure allows a process to block and wait for
+    \var{wvec} is a vector of output ports and integer file
-%    events on multiple I/O channels.  The \var{rvec} and \var{evec}
+    descriptors.  The procedure returns three vectors whose elements
-%    arguments are vectors of input ports and integer file descriptors;
+    are subsets of the corresponding arguments.  Every element of
-%    \var{wvec} is a vector of output ports and integer file
+    \var{rvec'} is ready for input; every element of \var{wvec'} is
-%    descriptors.  The procedure returns three vectors whose elements
+    ready for output; every element of \var{evec'} has an exceptional
-%    are subsets of the corresponding arguments.  Every element of
+    condition pending.
-%    \var{rvec'} is ready for input; every element of \var{wvec'} is
+   
-%    ready for output; every element of \var{evec'} has an exceptional
+    The \ex{select} call will block until at least one of the I/O
-%    condition pending.
+    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
+    The \var{timeout} value can be used to force the call to time-out
-%    channels passed to it is ready for operation.  The \var{timeout}
+    after a given number of seconds. It defaults to the special value
-%    value can be used to force the call to time-out after a given
+    \ex{\#f}, meaning wait indefinitely. A zero value can be used to
-%    number of seconds. It defaults to the special value \ex{\#f},
+    poll the I/O channels.
-%    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
-%    If an I/O channel appears more than once in a given
+    port's underlying integer file descriptor---only one of these two
-%    vector---perhaps occuring once as a Scheme port, and once as the
+    references may appear in the returned vector.  Buffered I/O ports
-%    port's underlying integer file descriptor---only one of these two
+    are handled specially---if an input port's buffer is not empty, or
-%    references may appear in the returned vector.  Buffered I/O ports
+    an output port's buffer is not yet full, then these ports are
-%    are handled specially---if an input port's buffer is not empty, or
+    immediately considered eligible for I/O without using the actual,
-%    an output port's buffer is not yet full, then these ports are
+    primitive \ex{select} system call to check the underlying file
-%    immediately considered eligible for I/O without using the actual,
+    descriptor.  This works pretty well for buffered input ports, but
-%    primitive \ex{select} system call to check the underlying file
+    is a little problematic for buffered output ports.
-%    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.
-%    The \ex{select!} procedure is similar, but indicates the subset of
+    Non-active I/O channels in the argument vectors are overwritten
-%    active I/O channels by side-effecting the argument vectors.
+    with {\sharpf} values.  The call returns the number of active
-%    Non-active I/O channels in the argument vectors are overwritten
+    elements remaining in each vector.  As a convenience, the vectors
-%    with {\sharpf} values.  The call returns the number of active
+    passed in to \ex{select!} are allowed to contain {\sharpf} values
-%    elements remaining in each vector.  As a convenience, the vectors
+    as well as integers and ports.
-%    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
-%    \remark{I have found the \ex{select!} interface to be the more
+      \texttt{select} sitting at the very heart of the Scheme 48/scsh
-%      useful of the two. After the system call, it allows you to check
+      I/O system, so \emph{all} multiplexed I/O is really
-%      a specific I/O channel in constant time.}
+      \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