Use Atoms for Independent State

An atom is Clojure’s everyday reference type for one independent piece of state. It is closest to a Java AtomicReference holding an immutable value, but the normal update style is functional: provide a function from old value to new value.

Use an atom when the state does not need to coordinate with another reference. Counters, local caches, in-memory configuration snapshots, and REPL-managed application state often fit.

Atom Basics

 1(def metrics
 2  (atom {:requests 0
 3         :errors 0}))
 4
 5(defn record-request! [ok?]
 6  (swap! metrics
 7         (fn [m]
 8           (-> m
 9               (update :requests inc)
10               (update :errors
11                       (fnil + 0)
12                       (if ok? 0 1))))))

The atom is mutable identity. The map stored inside it is still an immutable value. Each update produces a new map.

Why swap! Functions Must Be Pure

swap! reads the current value, applies your function, and tries to install the result. If another thread changed the atom first, Clojure may call your function again with a newer value.

That retry behavior is why update functions should not send emails, write files, publish messages, or call payment APIs.

1;; Avoid: the side effect could happen more than once.
2(swap! metrics
3       (fn [m]
4         (println "recording request")
5         (update m :requests inc)))

Keep the transition pure, then perform effects around it when needed.

1(defn increment-request [m]
2  (update m :requests inc))
3
4(defn record-request-and-log! []
5  (let [after (swap! metrics increment-request)]
6    (println "request count:" (:requests after))
7    after))

Good and Bad Fits

Java Review Questions

• Would this have been an AtomicReference, AtomicInteger, or synchronized setter in Java?
• Is there exactly one changing identity?
• Can the whole transition be represented as a pure function?
• Would another state location become inconsistent if this update succeeds alone?
• Could contention make the update function retry?

Knowledge Check