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'sstd::cellandstd::syncand OCaml'sAtomicare 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). @xandderefstay instd.coreas the protocolDeref(accepted), implemented by atoms and later bydelay, 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,readandwritedo 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 toatom.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'sRef.modifydoes, 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,disjand 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:assocon 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'sAgent: 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'sTVaror Clojure'sref) may come later if needed. - Hot loops need no atom: inside
loop/recura 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 testrecreates 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
simscheduler, reading an atom,swap!andreset!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.