source: trunk/abcl/doc/design/streams/design.html

Last change on this file was 12410, checked in by vvoutilainen, 15 years ago

Add documentation for the streams.

File size: 8.5 KB
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7<title>Design of lisp streams in ABCL</title>
8<style type="text/css">
9
10/*
11:Author: David Goodger (goodger@python.org)
12:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
13:Copyright: This stylesheet has been placed in the public domain.
14
15Default cascading style sheet for the HTML output of Docutils.
16
17See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
18customize this style sheet.
19*/
20
21/* used to remove borders from tables and images */
22.borderless, table.borderless td, table.borderless th {
23  border: 0 }
24
25table.borderless td, table.borderless th {
26  /* Override padding for "table.docutils td" with "! important".
27     The right padding separates the table cells. */
28  padding: 0 0.5em 0 0 ! important }
29
30.first {
31  /* Override more specific margin styles with "! important". */
32  margin-top: 0 ! important }
33
34.last, .with-subtitle {
35  margin-bottom: 0 ! important }
36
37.hidden {
38  display: none }
39
40a.toc-backref {
41  text-decoration: none ;
42  color: black }
43
44blockquote.epigraph {
45  margin: 2em 5em ; }
46
47dl.docutils dd {
48  margin-bottom: 0.5em }
49
50/* Uncomment (and remove this text!) to get bold-faced definition list terms
51dl.docutils dt {
52  font-weight: bold }
53*/
54
55div.abstract {
56  margin: 2em 5em }
57
58div.abstract p.topic-title {
59  font-weight: bold ;
60  text-align: center }
61
62div.admonition, div.attention, div.caution, div.danger, div.error,
63div.hint, div.important, div.note, div.tip, div.warning {
64  margin: 2em ;
65  border: medium outset ;
66  padding: 1em }
67
68div.admonition p.admonition-title, div.hint p.admonition-title,
69div.important p.admonition-title, div.note p.admonition-title,
70div.tip p.admonition-title {
71  font-weight: bold ;
72  font-family: sans-serif }
73
74div.attention p.admonition-title, div.caution p.admonition-title,
75div.danger p.admonition-title, div.error p.admonition-title,
76div.warning p.admonition-title {
77  color: red ;
78  font-weight: bold ;
79  font-family: sans-serif }
80
81/* Uncomment (and remove this text!) to get reduced vertical space in
82   compound paragraphs.
83div.compound .compound-first, div.compound .compound-middle {
84  margin-bottom: 0.5em }
85
86div.compound .compound-last, div.compound .compound-middle {
87  margin-top: 0.5em }
88*/
89
90div.dedication {
91  margin: 2em 5em ;
92  text-align: center ;
93  font-style: italic }
94
95div.dedication p.topic-title {
96  font-weight: bold ;
97  font-style: normal }
98
99div.figure {
100  margin-left: 2em ;
101  margin-right: 2em }
102
103div.footer, div.header {
104  clear: both;
105  font-size: smaller }
106
107div.line-block {
108  display: block ;
109  margin-top: 1em ;
110  margin-bottom: 1em }
111
112div.line-block div.line-block {
113  margin-top: 0 ;
114  margin-bottom: 0 ;
115  margin-left: 1.5em }
116
117div.sidebar {
118  margin: 0 0 0.5em 1em ;
119  border: medium outset ;
120  padding: 1em ;
121  background-color: #ffffee ;
122  width: 40% ;
123  float: right ;
124  clear: right }
125
126div.sidebar p.rubric {
127  font-family: sans-serif ;
128  font-size: medium }
129
130div.system-messages {
131  margin: 5em }
132
133div.system-messages h1 {
134  color: red }
135
136div.system-message {
137  border: medium outset ;
138  padding: 1em }
139
140div.system-message p.system-message-title {
141  color: red ;
142  font-weight: bold }
143
144div.topic {
145  margin: 2em }
146
147h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
148h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
149  margin-top: 0.4em }
150
151h1.title {
152  text-align: center }
153
154h2.subtitle {
155  text-align: center }
156
157hr.docutils {
158  width: 75% }
159
160img.align-left {
161  clear: left }
162
163img.align-right {
164  clear: right }
165
166ol.simple, ul.simple {
167  margin-bottom: 1em }
168
169ol.arabic {
170  list-style: decimal }
171
172ol.loweralpha {
173  list-style: lower-alpha }
174
175ol.upperalpha {
176  list-style: upper-alpha }
177
178ol.lowerroman {
179  list-style: lower-roman }
180
181ol.upperroman {
182  list-style: upper-roman }
183
184p.attribution {
185  text-align: right ;
186  margin-left: 50% }
187
188p.caption {
189  font-style: italic }
190
191p.credits {
192  font-style: italic ;
193  font-size: smaller }
194
195p.label {
196  white-space: nowrap }
197
198p.rubric {
199  font-weight: bold ;
200  font-size: larger ;
201  color: maroon ;
202  text-align: center }
203
204p.sidebar-title {
205  font-family: sans-serif ;
206  font-weight: bold ;
207  font-size: larger }
208
209p.sidebar-subtitle {
210  font-family: sans-serif ;
211  font-weight: bold }
212
213p.topic-title {
214  font-weight: bold }
215
216pre.address {
217  margin-bottom: 0 ;
218  margin-top: 0 ;
219  font-family: serif ;
220  font-size: 100% }
221
222pre.literal-block, pre.doctest-block {
223  margin-left: 2em ;
224  margin-right: 2em }
225
226span.classifier {
227  font-family: sans-serif ;
228  font-style: oblique }
229
230span.classifier-delimiter {
231  font-family: sans-serif ;
232  font-weight: bold }
233
234span.interpreted {
235  font-family: sans-serif }
236
237span.option {
238  white-space: nowrap }
239
240span.pre {
241  white-space: pre }
242
243span.problematic {
244  color: red }
245
246span.section-subtitle {
247  /* font-size relative to parent (h1..h6 element) */
248  font-size: 80% }
249
250table.citation {
251  border-left: solid 1px gray;
252  margin-left: 1px }
253
254table.docinfo {
255  margin: 2em 4em }
256
257table.docutils {
258  margin-top: 0.5em ;
259  margin-bottom: 0.5em }
260
261table.footnote {
262  border-left: solid 1px black;
263  margin-left: 1px }
264
265table.docutils td, table.docutils th,
266table.docinfo td, table.docinfo th {
267  padding-left: 0.5em ;
268  padding-right: 0.5em ;
269  vertical-align: top }
270
271table.docutils th.field-name, table.docinfo th.docinfo-name {
272  font-weight: bold ;
273  text-align: left ;
274  white-space: nowrap ;
275  padding-left: 0 }
276
277h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
278h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
279  font-size: 100% }
280
281ul.auto-toc {
282  list-style-type: none }
283
284</style>
285</head>
286<body>
287<div class="document" id="design-of-lisp-streams-in-abcl">
288<h1 class="title">Design of lisp streams in ABCL</h1>
289
290<div class="section" id="the-previous-design">
291<h1>The previous design</h1>
292<p>Previously, ABCL streams were built-in classes. This presented some problems for Gray streams,
293because ABCL CLOS can't use a built-in class as a base class, and Gray streams derive from
294a system-stream class. This was corrected by converting ABCL streams to be structure-objects
295instead of built-in classes, allowing CLOS to derive from the streams. There was, however, another
296problem that revealed a need to change the design in more drastic ways.</p>
297<div class="section" id="the-problem-with-the-previous-design">
298<h2>The problem with the previous design</h2>
299<p>While converting the streams from built-in classes to structure-objects allowed derivation,
300the pretty printer still didn't work with Gray streams. Gray streams replace the system stream
301functions, saving the old function symbols so that they can be later invoked. The pretty printer,
302however, just replaces the stream functions, and calls the low-level primitives directly, thus
303bypassing Gray streams completely. The attached image portrays the problem, where pprint will,
304for example, invoke %stream-write-char, thus bypassing any methods that there may be for
305stream-write-char using Gray streams.</p>
306<img alt="pprint-problem.png" src="pprint-problem.png" />
307</div>
308</div>
309<div class="section" id="the-planned-future-design-and-solution-to-the-problem">
310<h1>The planned future design and solution to the problem</h1>
311<p>The solution to the problem is quite similar to how SBCL does its streams. First of all, the pretty printer will
312no longer replace stream functions. The stream functionality will be based on closures in the slots of
313the structure-object representing the stream, and those closures will invoke low-level i/o functions that
314are stream-specific.</p>
315<p>The pretty printer will just setup closures that will extract the underlying stream
316object from a pprint-wrapped stream, and invoke its low-level functions. If pprint wrapping isn't present,
317the slots will contain closures that directly invoke low-level functions of streams. Gray streams will
318still replace the stream functions, because it's capable of invoking the replaced functions.</p>
319<p>In addition to these changes, it is planned that the stream function primitives will be moved from the Stream
320java class to a streamfunctions library, allowing the stream functions to be written in lisp rather than java.
321There's an ongoing aspiration to increase the lisp/java code ratio of ABCL, and this new design allows for that.</p>
322<img alt="pprint-solution.png" src="pprint-solution.png" />
323</div>
324</div>
325</body>
326</html>
Note: See TracBrowser for help on using the repository browser.