▼ 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.1 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.2 Procedures 4.21 Void 4.22 Undefined

#### 4.14BoxesðŸ”—â„¹

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.

 procedure(box v) → box? v : any/c
Returns a new mutable box that contains v.

 procedure 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.