contrib/sb-simple-streams/README

   1 -*- text -*-
   2
   3 An implementation of simple streams for sbcl.
   4
   5 Simple streams are an extensible streams protocol, with similar goals
   6 but different architecture than Gray streams.  Documentation about
   7 simple streams is available at
   8 http://www.franz.com/support/documentation/6.2/doc/streams.htm
   9
  10 This code was originally written by Paul Foley for cmucl; Paul's
  11 version resides (as of 2003-05-12) at
  12 http://users.actrix.co.nz/mycroft/cl.html
  13
  14 The port to sbcl was done by Rudi Schlatte (rudi@constantly.at).  Bug
  15 reports welcome.
  16
  17 ==================================================
  18
  19 Some sketchy notes about the simple-streams architecture, at least
  20 partly for my own benefit
  21
  22 (For all the details, please see Franz' documentation)
  23
  24 Motivation:
  25
  26 If you want to extend a given Gray stream, is it enough to supply a
  27 method for stream-write-byte, or do you have to overwrite
  28 stream-write-sequence as well?  How do you extend your Gray socket
  29 stream to support chunked stream encoding for HTTP/1.1?  Chances are
  30 that for any seriously interesting stream customization, you will
  31 implement some kind of buffer, collect data in it and
  32
  33
  34
  35 Simple streams is a layered architecture.  The device layer at the
  36 bottom deals with transferring chunks of bytes between a buffer and a
  37 device (socket, file, printer, what-have-you).  The top layer is the
  38 familiar CL API (read-line, write-sequence, open, etc).  The strategy
  39 layer in the middle translates between the buffer-of-bytes and CL
  40 stream world-view, dealing with byte<->character conversion,
  41 line-ending and stream-external-format conventions, etc.
  42
  43 Implementing a new type of stream is a matter of extending the right
  44 stream class and implementing device-read, device-write, device-extend
  45 & friends.  single-channel-simple-stream is a class where there is one
  46 buffer for both input and output (this is appropriate e.g. for a file).  The
  47 dual-channel-simple-stream class deals with devices that require
  48 separate buffers for input and output (e.g. sockets).
  49
  50 Other character representations (Unicode, other multi-byte encodings)
  51 are implemented at the strategy level.  The Franz documentation is
  52 unclear about this, but it seems that encodings take an active part
  53 ("the encoding reads as many bytes as are necessary to compose a
  54 character", or words to that effect).  This is not implemented in the
  55 present code (neither is it in Paul Foley's implementation), and will
  56 not be until sbcl gains Unicode abilities, but it would be nice to
  57 have it at least stubbed out in the implementation.