source: project/wiki/eggref/5/srfi-111 @ 39176

Last change on this file since 39176 was 39176, checked in by gnosis, 3 months ago

Documentation for SRFI-111 updated to version 0.2

File size: 8.4 KB
Line 
1== SRFI-111: Boxes
2=== Abstract
3Boxes are objects with a single mutable state. Several Schemes have them, sometimes called cells. A constructor, predicate, accessor, and mutator are provided.
4
5For more information see: [[https://srfi.schemers.org/srfi-111/|SRFI 111: Boxes]]
6=== Rationale
7A box is a container for an object of any Scheme type, including another box. It is like a single-element vector, or half of a pair, or a direct representation of state. Boxes are normally used as minimal mutable storage, and can inject a controlled amount of mutability into an otherwise immutable data structure (or one that is conventionally treated as immutable). They can be used to implement call-by-reference semantics by passing a boxed value to a procedure and expecting the procedure to mutate the box before returning.
8
9Some Scheme systems use boxes to implement set!. In this transformation, known as assignment conversion, all variables that are actually mutated are initialized to boxes, and all set! syntax forms become calls on set-box!. Naturally, all ordinary references to those variables must become calls on unbox. By reducing all variable mutation to data-structure mutation in this way, such Scheme systems are free to maintain variables in multiple hardware locations, such as the stack and the heap or registers and the stack, without worrying about exactly when and where they are mutated.
10
11Boxes are also useful for providing an extra level of indirection, allowing more than one body of code or data structure to share a reference, or pointer, to an object. In this way, if any procedure mutates the box in any of the data structures, all procedures will immediately "see" the new value in all data structures containing it.
12
13Racket and Chicken provide immutable boxes, which look like boxes to box? and unbox but which cannot be mutated. They are not considered useful enough to be part of this SRFI. If they are provided nevertheless, the recommended constructor name is immutable-box.
14
15The following table specifies the procedure names used by the Scheme implementations that provide boxes:
16
17<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
18
19
20<colgroup>
21<col  class="org-left" />
22
23<col  class="org-left" />
24
25<col  class="org-left" />
26
27<col  class="org-left" />
28
29<col  class="org-left" />
30
31<col  class="org-left" />
32
33<col  class="org-left" />
34
35<col  class="org-left" />
36</colgroup>
37<thead>
38<tr>
39<th scope="col" class="org-left">Proposed</th>
40<th scope="col" class="org-left"><a href="http://docs.racket-lang.org/reference/boxes.html">Racket</a></th>
41<th scope="col" class="org-left"><a href="http://www.iro.umontreal.ca/~gambit/doc/gambit-c.html#index-boxes">Gambit</a></th>
42<th scope="col" class="org-left"><a href="http://sisc-scheme.org/manual/html/ch03.html#Boxing">SISC</a></th>
43<th scope="col" class="org-left"><a href="http://www.scheme.com/csug7/objects.html#g50">Chez</a></th>
44<th scope="col" class="org-left"><a href="http://wiki.call-cc.org/eggref/4/box">Chicken</a></th>
45<th scope="col" class="org-left"><a href="http://web.mit.edu/scheme_v9.0.1/doc/mit-scheme-ref/Cells.html">MIT</a></th>
46<th scope="col" class="org-left"><a href="http://s48.org/1.1/manual/s48manual_42.html">Scheme48/scsh</a></th>
47</tr>
48</thead>
49<tbody>
50<tr>
51<td class="org-left">box</td>
52<td class="org-left">box</td>
53<td class="org-left">box</td>
54<td class="org-left">box</td>
55<td class="org-left">box</td>
56<td class="org-left">make-box</td>
57<td class="org-left">make-cell</td>
58<td class="org-left">make-cell</td>
59</tr>
60
61<tr>
62<td class="org-left">box?</td>
63<td class="org-left">box?</td>
64<td class="org-left">box?</td>
65<td class="org-left">box?</td>
66<td class="org-left">box?</td>
67<td class="org-left">box-mutable?</td>
68<td class="org-left">cell?</td>
69<td class="org-left">cell?</td>
70</tr>
71
72<tr>
73<td class="org-left">unbox</td>
74<td class="org-left">unbox</td>
75<td class="org-left">unbox</td>
76<td class="org-left">unbox</td>
77<td class="org-left">unbox</td>
78<td class="org-left">box-ref</td>
79<td class="org-left">cell-contents</td>
80<td class="org-left">cell-ref</td>
81</tr>
82
83<tr>
84<td class="org-left">set-box!</td>
85<td class="org-left">set-box!</td>
86<td class="org-left">set-box!</td>
87<td class="org-left">set-box!</td>
88<td class="org-left">set-box!</td>
89<td class="org-left">box-set!</td>
90<td class="org-left">set-cell-contents!</td>
91<td class="org-left">cell-set!</td>
92</tr>
93</tbody>
94</table>
95
96Note that Chicken also supports the procedure names defined by this SRFI in addition to its native API. Although the native API uses the standard naming pattern, for the purposes of this SRFI the unanimous voice of Racket, Gambit, SISC, and Chez is considered more significant.
97
98Racket, Gambit, SISC, Chez, and Chicken all support the lexical syntax #&datum to create a literal box (immutable in Racket, mutable in the other implementations). However, this SRFI does not. Incorporating a specifically mutable object into code makes it hard for an implementation to separate compile-time and run-time reliably, and it's not clear that providing them in data files provides enough benefit, as the box has to be located by tree-walking in any case. MIT Scheme and Scheme48/scsh do not provide a lexical syntax.
99
100The features specified in the autoboxing section of specification are based on those specified by RnRS for promises, which are analogous to immutable boxes except that their value is specified by code instead of data.
101=== Specification
102==== Procedures
103The following procedures implement the box type (which is disjoint from all other Scheme types), and are exported by the (srfi 111) library (or (srfi :111) on R6RS).
104
105<procedure>(box value)</procedure>
106
107Constructor. Returns a newly allocated box initialized to value.
108
109<procedure>(box? object)</procedure>
110
111Predicate. Returns {{#t}} if object is a box, and {{#f}} otherwise.
112
113<procedure>(unbox box)</procedure>
114
115Accessor. Returns the current value of box.
116
117<procedure>(set-box! box value)</procedure>
118
119Mutator. Changes box to hold value.
120
121The behavior of boxes with the equivalence predicates {{eq?}}, {{eqv?}}, and {{equal?}} is the same as if they were implemented with records. That is, two boxes are both {{eq?}} and {{eqv?}} iff they are the product of the same call to box and not otherwise, and while they must be {{equal?}} if they are {{eqv?}}, the converse is implementation-dependent.
122=== Implementation
123The Chicken 5 port used the R7RS reference implementation.  For details see [[https://srfi.schemers.org/srfi-111/|the original SRFI documentation]].  Version 0.1 of the Chicken port does '''not''' use the optional autoboxing (see below).
124==== Note that these implementations do not support the lexical syntax.
125==== Autoboxing (optional)
126The following provisions of this SRFI are optional:
127  * A procedure, whether system-provided or user-written, that expects a box as an argument but receives a non-box may, if appropriate, allocate a box itself that holds the value, thus providing autoboxing.
128
129  * A procedure that accepts arguments only of specified types (such as +) but receives a box instead may, if appropriate, unbox the box. Procedures that accept arguments of any type (such as cons) must not unbox their arguments.
130
131  * Calling unbox on a non-box may simply return the non-box.
132=== Author
133John Cowan
134Tests written by Kon Lovett
135Ported to Chicken Scheme 5 by Sergey Goldgaber
136=== Copyright
137Copyright (C) John Cowan 2013. All Rights Reserved.
138
139Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
140
141The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
142
143THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
144=== Version history
145==== 0.2 - Now using code from Kon Lovett's "box" module
146==== 0.1 - Ported to Chicken Scheme 5
Note: See TracBrowser for help on using the repository browser.