References are objects that point to other objects. References are usually mutable, i.e. they have a state.

State related namespaces
  • dunaj.state - Stateful objects. References, mutation, cloning, etc.

  • dunaj.state.basic - Atom, Box, Local and other basic reference types

  • dunaj.state.ref - Refs, a transactional references that use software transactional memory (STM) for safe shared use of mutable references

  • dunaj.state.var - Vars, references with mutable root binding and thread local bindings that can be rebound dynamically

  • dunaj.state.weak - Weak and soft references

Stateful objects that represent the result of an asynchronous computation are described in the Concurrency page.

Stateful objects that represent the system or network resource are described in the Resources page.

Dunaj defines following basic references:

  • box - A basic immutable reference

  • local - A thread local reference

  • unsynchronized-reference

    • A low level unsynchronized reference

  • volatile-reference

    • A low level volatile reference

  • atom - A reference that manages synchronous state

  • ref - A transactional reference that uses software transactional memory (STM)

  • Var - A references with mutable root binding and thread local bindings that can be rebound dynamically.

  • weak and soft references that control the garbage collection of the values they point to

The very basic feature of a reference is that it can be dereferenced in order to get it’s current state. This property is in Dunaj represented by IReference and IBlockingReference protocols.

The way how a reference object changes its state depends on the type of the reference. Following protocols are available:

Dunaj further provides several protocols and functions that are used to define and manage auxiliary state (e.g. pending status of lazy seqs, open status for resources)

Dunaj streamlines the cloning of reference objects by introducing ICloneable protocol. The clone function returns a cloned object. Value objects returns themselves and references that do not support cloning must throw.




  • immutable

  • an expression that cannot be evaluated any further

  • number, constant, fact?

  • 'A value is a location on a dimension, and may be quantitative or qualitative'.


  • objects’s value at a point in time

  • actual value of a reference

  • can change

  • ability of an object to relate to a different value in different points of time

  • object can have multiple such states. Even some value objects have an auxiliary state


  • contains state and has the ability to manage it and to put object/reference into other state (associate object with different value), initiated by either user or some external forces.

Stateful types:

"observability: an operation is said to be stateful if you can observe that its state has changed, e.g. by repeating the same operation with the same arguments but getting different results. Such an operation depends on state which is not provided as part of invoking the operation."

"an object has state if its behavior (as defined by its methods) may observably change over the course of time. In other words, the output of (the methods of) a stateful object is determined not only by the input received, but also by some modifiable internal state."