4.14 Boxes

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

▼ | 4 | Datatypes

4.1 | Equality
4.2 | Booleans
4.3 | Numbers
4.4 | Strings
4.5 | Byte Strings
4.6 | Characters
4.7 | Symbols
4.8 | Regular Expressions
4.9 | Keywords
4.10 | Pairs and Lists
4.11 | Mutable Pairs and Lists
4.12 | Vectors
4.13 | Stencil Vectors
4.14 | Boxes
4.15 | Hash Tables
4.16 | Treelists
4.17 | Sequences and Streams
4.18 | Dictionaries
4.19 | Sets
4.20 | Procedures
4.21 | Void
4.22 | Undefined

On this page:

box?
box
box-immutable
unbox
set-box!
unbox*
set-box*!
box-cas!

Racket
top contents ← prev up next →

### 4.14 Boxes🔗ℹ

> > > Boxes in The Racket Guide introduces boxes.

A box is like a single-element vector, normally used as minimal mutable storage.

A box can be mutable or immutable. When an immutable box is provided to a procedure like set-box!, the exn:fail:contract exception is raised. Box constants generated by the default reader (see Reading Strings) are immutable. Use immutable? to check whether a box is immutable.

A literal or printed box starts with #&. See Reading Boxes for information on reading boxes and Printing Boxes for information on printing boxes.

> procedure (box? v) → boolean?
> v : any/c

Returns #t if v is a box, #f otherwise.

See also immutable-box? and mutable-box?.

> procedure (box v) → box?
> v : any/c

Returns a new mutable box that contains v.

> procedure (box-immutable v) → (and/c box? immutable?)
> v : any/c

Returns a new immutable box that contains v.

> procedure (unbox box) → any/c
> box : box?

Returns the content of box.

For any v, (unbox (box v)) and (unbox (box-immutable v)) returns v.

> procedure (set-box! box v) → void?
> box : (and/c box? (not/c immutable?))
> v : any/c

Sets the content of box to v.

> procedure (unbox* box) → any/c
> box : (and box? (not/c impersonator?))
> procedure (set-box*! box v) → void?
> box : (and/c box? (not/c immutable?) (not/c impersonator?))
> v : any/c

Like unbox and set-box!, but constrained to work on boxes that are not impersonators.

Added in version 6.90.0.15 of package base.

> procedure (box-cas! box old new) → boolean?
> box : (and/c box? (not/c immutable?) (not/c impersonator?))
> old : any/c
> new : any/c

Atomically updates the contents of box to new, provided that box currently contains a value that is eq? to old, and returns #t in that case. If box does not contain old, then the result is #f.

If no other threads or futures attempt to access box, the operation is equivalent to

> (and (eq? old (unbox box)) (set-box! box new) #t)

except that box-cas! can spuriously fail on some platforms. That is, with low probability, the result can be #f with the value in box left unchanged, even if box contains old.

When Racket is compiled with support for futures, box-cas! is guaranteed to use a hardware compare and set operation. Uses of box-cas! can be performed safely in a future (i.e., allowing the future thunk to continue in parallel). See also Machine Memory Order.

top contents ← prev up next →