atom module

Based on Clojure atoms (except that watch functions and validators aren’t implemented), i.e. a holder for a changing value; also includes default implementation for most operations (with synchronicity expectation, but they’re supposed to be atomic anyway), so to implement your own atom you only need to define deref as well as one of reset, resetVals, swap or swapVals for it. These functions can be used with RAtoms and RCursors.

All functions except for atom are multimethods dispatched by argument type (class).

atom (x)

Produces a regular atom holding x (undefined if nothing was passed).

atom(42)  // ⇒ Atom(42)

deref (atom)

Returns the value held by atom (also in Wisp: @atom).

var x = atom(42)
deref(x)  // ⇒ 42

reset (atom, value)

Replaces the value held by atom with value (value is returned).

var x = atom(42)
reset(x, 10)  // ⇒ 10
deref(x)      // ⇒ 10

resetVals (atom, value)

Replaces the value held by atom with value ([oldValue, value] is returned).

var x = atom(42)
resetVals(x, 10)  // ⇒ [42, 10]
deref(x)          // ⇒ 10

swap (atom, f, ...args)

Updates the value held by atom by applying function f on it (the new value is returned).

var x = atom({answer: 42})
swap(x, assoc, 'foo', 10) // ⇒ {answer: 42, foo: 10}
deref(x)                  // ⇒ {answer: 42, foo: 10}

swapVals (atom, f, ...args)

Updates the value held by atom by applying function f on it ([oldValue, newValue] is returned).

var x = atom({answer: 42})
swapVals(x, assoc, 'foo', 10) // ⇒ [{answer: 42}, {answer: 42, foo: 10}]
deref(x)                      // ⇒ {answer: 42, foo: 10}

compareAndSet (atom, oldval, newval)

Replaces the value held by atom with newval if the current value is identical to oldval (true/false is returned depending on success).

var x = atom(42),  y = atom({answer: 42})
compareAndSet(x, 42, 12)           // ⇒ true
deref(x)                           // ⇒ 12
compareAndSet(x, 42, 11)           // ⇒ false /* because @x is 12 */
deref(x)                           // ⇒ 12
compareAndSet(y, {answer: 42}, 12) // ⇒ false /* because @y is not the same dict */
deref(y)                           // ⇒ {answer: 42}