0.9.16.28:
[sbcl.git] / 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.