Refs, a transactional references that use software transactional memory (STM) for safe shared use of mutable references.

Refs allow mutation to occur only within a transaction. Transactions ensure that all actions on Refs are atomic, consistent, and isolated.

Transactions are retried in case a conflict arises, so the code inside transactions should be I/O and side-effect free. Note that agents play nicely with transactions, as sends from within a transaction are dispatched only when the transaction is successful.
Refs are abstracted into IRef protocol, as there can be multiple implementations of Refs (e.g. cgrand’s Megarefs)

alter

Available since version 1.0 (view source)

Usage:
  • (alter ref f & args)

Type signature:
  • (IRef ⨯ AnyFn ⨯ (Va Any)) → Any

Must be called in a transaction. Sets the in-transaction-value of ref to: (apply f in-transaction-value-of-ref args) and returns the in-transaction-value of ref.

See also: commute, ensure, reset, ref, dosync

commute

Available since version 1.0 (view source)

Usage:
  • (commute ref f & args)

Type signature:
  • (IRef ⨯ AnyFn ⨯ (Va Any)) → Any

Must be called in a transaction. Sets the in-transaction-value of ref to: (apply f in-transaction-value-of-ref args) and returns the in-transaction-value of ref. At the commit point of the transaction, sets the value of ref to be: (apply f most-recently-committed-value-of-ref args)

Thus f should be commutative, or, failing that, you must accept last-one-in-wins behavior. commute allows for more concurrency than reset.

See also: alter, reset, ref, dosync

dosync

Available since version 1.0 (alias of clojure.core/dosync)

MACRO (dosync & exprs)

Runs the exprs (in an implicit do) in a transaction that encompasses exprs and any nested calls. Starts a transaction if none is already running on this thread. Any uncaught exception will abort the transaction and flow out of dosync.

The exprs may be run more than once, but any effects on Refs will be atomic.

ensure

Available since version 1.0 (view source)

Usage:
  • (ensure ref)

Type signature:
  • (IRef) → Any

Must be called in a transaction. Protects the ref from modification by other transactions. Returns the in-transaction-value of ref. Allows for more concurrency than (reset ref @ref).

See also: reset, ref, dosync

history-count

Available since version 1.0 (view source)

not referred automatically

Usage:
  • (history-count ref)

Type signature:
  • (IRef) → Integer+

Returns the history count of a ref. Min and max history parameters are stored and can be changed in ref’s mutable config.

ref

Available since version 1.0 (alias of clojure.core/ref)

Usage:
  • (ref x)

  • (ref x & options)

Type signatures:
  • (Any) → IRef

  • (Any ⨯ (Va Any)) → IRef

Creates and returns a Ref with an initial value of x and zero or more options:

  • :meta metadata-map - If supplied, it will become the metadata on the ref.

  • :validator validate-fn - must be nil or a side-effect-free fn of one argument, which will be passed the intended new state on any state change. If the new state is unacceptable, the validate-fn should return false or throw an exception. validate-fn will be called on transaction commit, when all refs have their final values.

  • :min-history (default 0) :max-history (default 10) - Normally refs accumulate history dynamically as needed to deal with read demands. If you know in advance you will need history you can set :min-history to ensure it will be available when first needed (instead of after a read fault). History is limited, and the limit can be set with :max-history.

History parameters can be later changed through ref’s mutable configuration. Validator may be also set and managed through its functions in dunaj.feature namespace.

See also: dosync, ref?, reset, alter, commit, ensure

ref?

Available since version 1.0 (view source)

Usage:
  • (ref? x)

Type signature: Predicate

Returns true if object x satisfies IRef protocol, false otherwise.

See also: IRef, ref, dosync

reset

Available since version 1.0 (view source)

Usage:
  • (reset ref val)

Type signature:
  • (IRef ⨯ Any) → Any

Must be called in a transaction. Sets the value of ref. Returns val.

See also: alter, commute, ensure, ref, dosync