(lispkit box)

LispKit is a R7RS-compliant implementation with one exception: pairs are immutable. This library provides implementations of basic mutable data structures with reference semantics: mutable multi-place buffers, also called boxes, mutable pairs, and atomic boxes. The difference between a two-place box and a mutable pair is that a mutable pair allows mutations of the two elements independent of each other. The difference between a box and an atomic box is that access to atomic boxes is synchronized such that reading and writing is atomic.

Boxes

(box? obj)

Returns #t if obj is a box; #f otherwise.

(box obj ...)

Returns a new box object that contains the objects obj ....

(unbox box)

Returns the current contents of box. If multiple values have been stored in the box, unbox will return multiple values. This procedure fails if box is not referring to a box.

(set-box! box obj ...)

Sets the content of box to objects obj .... This procedure fails if box is not referring to a box.

(update-box! box proc)

Invokes proc with the content of box and stores the result of this function invocation in box. update-box! is implemented like this:

(define (update-box! box proc)
  (set-box! box (apply-with-values proc (unbox box))))

Mutable pairs

(mpair? obj)

Returns #t if v is a mutable pair (mpair); #f otherwise.

(mcons car cdr)

Returns a new mutable pair whose first element is set to car and whose second element is set to cdr.

(mcar mpair)

Returns the first element of the mutable pair mpair.

(mcdr mpair)

Returns the second element of the mutable pair mpair.

(set-mcar! mpair obj)

Sets the first element of the mutable pair mpair to obj.

(set-mcdr! mpair obj)

Sets the second element of the mutable pair mpair to obj.

Atomic boxes

atomic-box-type-tag

Symbol representing the atomic-box type. The type-for procedure of library (lispkit type) returns this symbol for all atomic box objects.

(atomic-box? obj)

Returns #t if obj is an atomic box; #f otherwise.

(make-atomic-box obj ...)

Returns a new atomic box that contains the objects obj ....

(atomic-box-ref abox)

Returns the current contents of atomic box abox synchronizing access such that it is atomic. If multiple values have been stored in abox, atomic-box-ref will return multiple values. This procedure fails if abox is not referring to an atomic box.

(atomic-box-set! abox obj ...)

Sets the content of abox to objects obj ... synchronizing access such that it is atomic. This procedure fails if abox is not referring to an atomic box.

(atomic-box-swap! abox obj ...)

Sets the content of abox to objects obj ... synchronizing access such that it is atomic. This procedure fails if abox is not referring to an atomic box. This procedure returns the former values of abox.

(atomic-box-compare-and-set! abox curr obj ...)

Sets the content of abox to objects obj ... if the values of abox match curr; in this case #t is returned. If the values of abox do not match curr, the values of abox remain untouched and #f is returned. This operation is atomic and fails if abox is not referring to an atomic box.

(atomic-box-compare-and-swap! abox curr obj ...)

Sets the content of abox to objects obj ... if the values of abox match curr. If the values of abox do not match curr, the values of abox remain untouched. This operation is atomic and fails if abox is not referring to an atomic box. It returns the former values of abox.

(atomic-box-inc+mul! abox i1) (atomic-box-inc+mul! abox i1 m) (atomic-box-inc+mul! abox i1 m i2)

This procedure can be used for atomic boxes containing a single value of type flonum or fixnum to update its value x with (x + i1) * m + i2 in a synchronized fashion. atomic-box-inc+mul! returns the new value of abox.

(atomic-box-update! abox proc)

Invokes proc with the content of abox and stores the result of this function invocation in abox. The computation of the new value and the update of abox is performed atomically and the new value of abox is returned by atomic-box-update!.