# (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:
```scheme
(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*****)** \
\&#xNAN;**(atomic-box-inc+mul! *****abox i1 m*****)**\
\&#xNAN;**(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!`.