change to `make-input-port' and `make-output-port'

[Matthew Flatt <mflatt@cs.utah.edu>]

To support general non-blocking input and output operations on all
ports, we need to revise the interface of `make-input-port' and
`make-output-port'. The new interface is defined below.

This interface is quite different from the old one. It makes each port
responsible for implementing non-blocking, string-based I/O instead of
blocking, character-based I/O. The old interface doesn't map well to
the new one in the case of input, and not at all in the case of output.

Since this is such a big change for a relatively useful set of
procedures, and since there's no good path for backward compatibility,
I wonder whether anyone thinks that adapting their code to the new
interface would be prohibitively difficult. Let me know if so.

Thanks,
Matthew

----------------------------------------

  (make-input-port waitable-or-#f
                   read-proc
                   peek-proc-or-#f
                   close-proc)

      waitable-or-#f :
         This waitable object (e.g., a semaphore or another port) is
         used by the system with `object-wait-multiple' to block until
         input/EOF is ready for reading/peeking. If the waitable is a
         semaphore, it will be re-posted after a block completes. The
         system will not allow user code to access the object.

         The port's reading and peeking procedures need not return
         data when the waitable unblocks, but spurious unblocks will
         reduce the port's performance. For example, a waitable might
         unblock when no data is available as a way of detecting
         demand on the port.

         The waitable will not always be used before a call to a
         reading or peeking procedure (e.g., for a non-blocking
         read).

         Supplying #f instead of a waitable indicates that input/EOF
         is always available. In other words, it's the same as
         (make-semaphore 1).

      read-proc : (string -> int-or-eof)
         Fills the given string and returns the number of read characters,
         or returns EOF (without putting any characters into the string).

         Errors can be reported by raising an exception, but only if no
         characters are read.

         A port's reading procedure may be called in multiple threads
         simultaneously. The port is reposnsible for its own internal
         synchronization.

      peek-proc : (string -> int-or-eof)
         Optional; the protocol is the same as read, except that the
         port keeps all characters.

      close-proc : (-> void)
         Called when the port is closed. The port's waitable, reading
         procedure, peeking procedure, and closing procedure will
         never be used again via the port after this procedure
         returns. However, the procedure can be called simultaneously
         in multiple threads.



  (make-output-port waitable-or-#f
                    write-proc
                    close-proc)

      waitable-or-#f :
         As for input ports, but to indicate that a non-blocking write
         is likely to write at least one character.

      write-proc : (immutable-string start-int end-int flush? -> int)
         Writes as much of the given range of the given string as
         possible without blocking. Returns the number of characters
         written (or buffered).

         If `flush?' is false, then the port can buffer characters at
         will, instead of immediately committing them. From a user's
         perspective, the different between buffered and committed
         data is (1) buffered data can be lost in the future due to a
         failed commit, and (2) `flush-output' forces all buffered
         data to be committed.

         If `flush?' is true, previously buffered characters must be
         committed before the write, and newly written characters
         should not be buffered. When the `flush-output' procedure is
         applied to the port after one or more non-flushed writes, the
         write procedure is called with an empty string and a true
         value for `flush?'.

         If the writing procedure raises an exception, due either to
         write or commit operations, it must not have written any
         characters (though it may have committed previously written
         characters).

         A port's writing procedure may be called in multiple threads
         simultaneously. The port is reposnsible for its own internal
         synchronization.

      close-proc : (-> void)
         Called when the port is closed.  The port's waitable, writing
         procedure, and close procedure will never be used again via
         the port after this procedure returns. However, the procedure
         can be called simultaneously in multiple threads.