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 that avoids some
   6 problems with Gray streams.
   7
   8 Documentation about simple streams is available at
   9 http://www.franz.com/support/documentation/6.2/doc/streams.htm
  10
  11 This code was originally written by Paul Foley for cmucl; Paul's
  12 version is now in cmucl cvs.
  13
  14 The port to sbcl was done by Rudi Schlatte (rudi@constantly.at).
  15
  16 This implementation should be considered Alpha-quality; the basic
  17 framework is there, but many classes are just stubs at the moment.
  18 See simple-stream-test.lisp for things that should work.
  19
  20
  21
  22 Known differences to the ACL behaviour:
  23
  24 - open not return a simple-stream by default.  This can be
  25   adjusted; see default-open-class in the file cl.lisp
  26
  27
  28
  29
  30
  31 ==================================================
  32
  33 Some sketchy notes about the simple-streams architecture, at least
  34 partly for my own benefit
  35
  36 (For all the details, please see Franz' documentation)
  37
  38 Motivation:
  39
  40 If you want to extend a given Gray stream, is it enough to supply a
  41 method for stream-write-byte, or do you have to overwrite
  42 stream-write-sequence as well?  How do you extend your Gray socket
  43 stream to support chunked stream encoding for HTTP/1.1?  Is
  44 stream-read-char-no-hang required to call stream-listen, then
  45 stream-read-char?  Simple-streams solve these protocol problems by
  46 implementing a device layer following a buffering protocol and a thin
  47 "strategy" layer that provides the functionality for the normal CL
  48 stream semantics.
  49
  50 The device layer at the bottom deals with transferring chunks of bytes
  51 between a buffer and a device (socket, file, printer, what-have-you).
  52 The top layer is the familiar CL API (read-line, write-sequence, open,
  53 etc).  The strategy layer in the middle translates between the
  54 buffer-of-bytes and CL stream world-view, dealing with
  55 byte<->character conversion, line-ending and stream-external-format
  56 conventions, etc.
  57
  58 Implementing a new type of stream is a matter of extending the right
  59 stream class and implementing device-read, device-write, device-extend
  60 & friends.  single-channel-simple-stream is a class where there is one
  61 buffer for both input and output (this is appropriate e.g. for a file).  The
  62 dual-channel-simple-stream class deals with devices that require
  63 separate buffers for input and output (e.g. sockets).
  64
  65 Other character representations (Unicode, other multi-byte encodings)
  66 are implemented at the strategy level.  The Franz documentation is
  67 unclear about this, but it seems that encodings take an active part
  68 ("the encoding reads as many bytes as are necessary to compose a
  69 character", or words to that effect).  This is not implemented in the
  70 present code (neither is it in Paul Foley's implementation), and will
  71 not be until sbcl gains Unicode abilities, but it would be nice to
  72 have it at least stubbed out in the implementation.