On this page:
box?
box
box-immutable
unbox
set-box!
box-cas!

3.12 Boxes

+Boxes in The Racket Guide introduces boxes.

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

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

(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)) 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

(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 loc)) (set-box! loc new) #t)

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