From 666f5282f844aa26865ee7d4b6337fdc19dda1e2 Mon Sep 17 00:00:00 2001
From: sperber <sperber>
Date: Thu, 28 Nov 2002 10:54:22 +0000
Subject: [PATCH] Added documentation for WAIT-PORTS.

---
 RELEASE                      | 13 +++++++------
 doc/scsh-manual/syscalls.tex | 28 ++++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/RELEASE b/RELEASE
index fdb8c8e..2dc87a4 100644
--- a/RELEASE
+++ b/RELEASE
@@ -188,14 +188,15 @@ We manage the project using SourceForge:
    checksums.
 
 ** API changes
-   select and select! are supported again
-   Interface to the uname function
-   Direct interface to the directory stream operations
+   select and select! are supported again.  Note however, that they
+   are deprecated in favor of the new wait-ports procedure.
+   New interface to the uname function.
+   New direct interface to the directory stream operations
    New structure scheme-with-scsh which combines the exports of the
-     modules scsh and scheme
+     modules scsh and scheme, avoiding duplicates
    New procdures to work directly on file-info records
-   The procedure repl has been removed
-	
+   The repl procedure has been removed
+
 ** Bugfixes
 
 
diff --git a/doc/scsh-manual/syscalls.tex b/doc/scsh-manual/syscalls.tex
index 6316ee1..688c22a 100644
--- a/doc/scsh-manual/syscalls.tex
+++ b/doc/scsh-manual/syscalls.tex
@@ -818,7 +818,7 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
     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
@@ -835,9 +835,33 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
       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.}
+      but one of them.
+      
+      In any case, the \texttt{wait-ports} procedure described below
+      is usually a preferable alternative to
+      \texttt{select}/\texttt{select!}: it is much simpler to use, and
+      also has a slightly more efficient implementation.}
 \end{desc}
 
+\defun {wait-ports}{timeout port \ldots}{ready-ports}
+\begin{desc}
+  The \ex{wait-ports} call will block until at least one of the ports
+  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.
+    
+  The \var{timeout} value can be used to force the call to time-out
+  after a given number of seconds.  A value of \ex{\#f} means to wait
+  indefinitely.  A zero value can be used to poll the ports.
+
+  \texttt{Wait-ports} returns a list of the ports ready for
+  operation.  Note that this list may be empty if the timeout expired
+  before any ports became ready.
+\end{desc}
+
+
 \begin{defundescx}{write-string}{string [fd/port start end]}\undefined
     This procedure writes all the data requested. 
     If the procedure cannot perform the write with a single kernel call