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