Choose Practical Ref Use Cases

Refs are a focused tool. They are excellent when a small set of in-memory identities must move together, and they are a poor substitute for a database, durable queue, or distributed lock.

Use them when the coordination problem is local to one JVM and the invariant is important enough to justify a transaction.

Good and Bad Fits

The line is practical: if losing the state on JVM restart is unacceptable, refs should not be the source of truth.

Example: Primary Map and Index

This example keeps a user map and an email index consistent. Either both refs update, or neither does.

 1(def users-by-id (ref {}))
 2(def id-by-email (ref {}))
 3
 4(defn add-user! [user]
 5  (dosync
 6    (let [{:keys [id email]} user]
 7      (when (contains? @id-by-email email)
 8        (throw
 9          (ex-info "email already used"
10                   {:email email})))
11      (alter users-by-id assoc id user)
12      (alter id-by-email assoc email id))))

This is a good ref example because the two refs represent different identities with one invariant: email lookup must point at the same user stored by id.

If This Were Java

STM can simplify in-memory coordination, but it should not blur the boundary between memory and persistence.

Production Guidance

• Keep refs private to a component or namespace when possible.
• Store ordinary immutable data in refs.
• Use refs for derived or process-local coordination unless you have a clear reason otherwise.
• Keep transaction bodies small enough to review.
• Prefer a database transaction when business correctness depends on durability.

Knowledge Check