SRFI-111: Boxes
Abstract
Boxes are objects with a single mutable state. Several Schemes have them, sometimes called cells. A constructor, predicate, accessor, and mutator are provided.
For more information see: SRFI 111: Boxes
Rationale
A 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.
Some 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.
Boxes 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.
Racket 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.
The following table specifies the procedure names used by the Scheme implementations that provide boxes:
Note 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.
Racket, 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.
The 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.
Specification
Procedures
The 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).
- box valueprocedure
Constructor. Returns a newly allocated box initialized to value.
- box? objectprocedure
Predicate. Returns #t if object is a box, and #f otherwise.
- unbox boxprocedure
Accessor. Returns the current value of box.
- set-box! box valueprocedure
Mutator. Changes box to hold value.
The 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.
Implementation
The Chicken 5 port used the R7RS reference implementation. For details see the original SRFI documentation. Version 0.1 of the Chicken port does not use the optional autoboxing (see below).
Note that these implementations do not support the lexical syntax.
Autoboxing (optional)
The following provisions of this SRFI are optional:
* 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.
* 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.
* Calling unbox on a non-box may simply return the non-box.
Author
- John Cowan
- Tests written by Kon Lovett
- Ported to Chicken Scheme 5 by Sergey Goldgaber
Repository
This egg is hosted on the CHICKEN Subversion repository:
https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/srfi-111
If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.
Copyright
Copyright (C) John Cowan 2013. All Rights Reserved.
Permission 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:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE 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.