* Goal

A buffer management interface that the standard stream-related
functions can call, so that streams can be implemented whose
underlying IO is done by means other than read() write() to a unix
file descriptor.

* Scope

** IO Layer

The implementation of this interface provides a buffer to its client.
The client may read or write to this buffer as appropriate, and send
messages to the implementation to empty the buffer when full, or fill
it when empty.

Current thinking is to be element-width-agnostic here: should there be
an external IO entity that expects UCS-4 characters, for example, it
would be silly for us to translate everything down to (unsigned-byte 8)
before letting it get at the buffer.

Methods: fill-buffer, write-and-empty-buffer, some control over
position within the buffer


** Translation layers

Translation layers are responsible for converting the elements that a
user writes to his stream into whatever width of unsigned-byte is
expected by the IO Layer.  Translators may be chained, so for example
a stream that outputs SSLified HTTP-chunked gzipped UTF8 from a
stream element-type of unicode-character would be possible by plugging
the relevant translations together.

How does this work?  Haven't thought about it yet


* TO DO

can we add stuff to help in the implementation of funny ansi stream
types (e.g. broadcast, concatenated streams) at this level?

blocking/half-blocking/non-blocking operations

try to define boundary (buffer full/empty) cases in such a way
that it's not massively painful to cope when e.g. we have a
utf8-encoded character split over a buffer boundary

unreading elements