Skip to the content
Diaspar

Decision D027 · accepted; details proposed

Mutable cells (atoms)

A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.

Status: accepted (2026-11-15) for having atoms with Clojure's vocabulary; accepted (2026-11-16) for what swap! guarantees; proposed for the rest

Decision

Values are immutable (D004, D013); the one place where state changes is a cell, an atom as in Clojure, holding an immutable value.

(use std.atom)

(def counter (atom.new 0))
(atom.swap! counter inc)       ; applies a function to the current value
(atom.reset! counter 10)       ; replaces the value
@counter                       ; reads it; the same as (deref counter)

(def log (atom.new #[]))
(atom.swap! log conj "started")
  • Atoms live in the module std.atom, not in the prelude (accepted, 2026-11-16): atom.new, atom.swap!, atom.reset!. State is visible at the import: a module without (use std.atom) creates no atoms, as Rust's std::cell and std::sync and OCaml's Atomic are imported. In a language with effects, atoms are rare, and the prelude stays free of them. The verbs and the ! that marks a change of state follow Clojure (D009).
  • @x and deref stay in std.core as the protocol Deref (accepted), implemented by atoms and later by delay, task results and other references.
  • Operations on atoms are an effect in inferred types (accepted): creating, reading, and changing a cell appear in a function's effects, as alloc, read and write do in Koka. The effect is tracked, not handled: there is no handler to install and no cost at run time. It is what lets the compiler prove that a function passed to atom.swap! does not touch cells (below), and what checks that macros read no cells while expanding (D015). Its name is proposed: Mut. The bootstrap interpreter infers no effects, so there it is checked only at run time.
  • Cells are where cycles can form, so the cycle collector looks only at them (D004).
  • Macros may not read cells while expanding (D015).
  • Needed now for capturing output in tests (term.capture), simulating command lines (cli.simulate), caches, and counters: a handler answers in place (D005), so state a handler accumulates lives in a cell.

What swap! guarantees (accepted)

The semantics are Clojure's:

  • An atom is never empty. While the function runs, the atom holds the old value; if the function raises, the old value stays; a function that reads its own atom sees the old value.
  • Under contention the function runs again. An atom shared between tasks is updated with compare-and-swap, so the function may run more than once and should have no effects.
  • In place is an optimization, not a second semantics. The compiler may take the value out of the atom, update it in place, and put it back, when it has proved through effect types (D005) that the function cannot raise or touch cells (no error effects and no Mut), and the atom is not shared with another task. Nobody can then observe the empty atom, so the program cannot tell the difference. This is what Lean 4's Ref.modify does, which is safe there because its functions are pure. Where nothing is proved (the REPL, where types only warn, D007), the old value is kept, and an update without the only reference copies the value: vectors are flat arrays (D026 [6]), so (atom.swap! log conj x) would copy the whole vector. The common updates must therefore take the in-place path: built-in functions known not to raise or touch cells (conj, assoc, dissoc, disj and similar) qualify without any inference, in the interpreter as well as the compiler. Whether a call can raise is decided from its arguments before the update: assoc on a vector qualifies when the index is within its length, on a map always (accepted, 2026-11-16).
  • State that changes with effects belongs to an actor from std.actor (D035), as Elixir's Agent: its handler runs once per message. Several cells changed together, with effects, may later be cowns (std.cown, an experiment in D035); transactions over several cells (STM, as Haskell's TVar or Clojure's ref) may come later if needed.
  • Hot loops need no atom: inside loop/recur a value is already unique, and Perceus updates it in place (D004). Atoms are for shared state.

Rejected:

Alternative Where Why not
Taking the value out during the function Rust's Cell::take and RefCell the atom is empty after a failure, losing REPL state; a function that reads its atom fails; no retry under contention
A lock with in-place update Rust's Mutex, Swift's inout deadlocks; after a failure, Rust's poisoning or Swift's partly updated value
Restoring on failure under a lock Haskell's modifyMVar_ waiting and deadlocks for what compare-and-swap does without them

Atoms at the top level of a module (accepted, 2026-11-16)

Global mutable state is a classic source of bugs: tests that affect each other, changes nobody can trace, races. An atom inside a function or a handler is local state and needs no notice; an atom defined at the top level of a module is shared by everything that loads the module.

  • A warning for (def name (atom.new …)) at the top level: "module-level state: tests and the REPL share this atom", with help "pass the state as an argument, or keep it in an actor". It is silenced by marking the definition ^:state, for the cases where a program needs it (a cache, the state of a live server).
  • diaspar test recreates top-level atoms before each test, so tests do not affect each other through module state (D016).
  • The same holds for channels and cowns made at the top level of a module (proposed, 2026-11-17, D035): they are module state too.

Proposed

  • Reading increments the count of the value read, so a concurrent reset! cannot free it under the reader (research: reports/Runtime and C backend design).
  • Under the sim scheduler, reading an atom, swap! and reset! are scheduling points, so a test explores the interleavings of tasks that share an atom (D035; design/concurrency.md §6.3).
  • Watches and validators as in Clojure come later, if needed.