Browse Clojure Foundations for Java Developers
-
-
- 4.1 Introduction to the REPL
- 4.2 Evaluating Expressions
- 4.3 Defining and Testing Functions
- 4.4 REPL-Driven Development
- 4.5 Handling Errors and Debugging in the REPL
- 4.6 Using the REPL in Various Editors/IDEs
- 4.7 Integrating REPL with Build Tools
- 4.8 Hot Reloading Code
- 4.9 Best Practices for REPL Usage
- 4.10 REPL vs Java's `main` Method
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Agents
Agents manage asynchronous, independent state changes: queue actions with send/send-off and handle failures explicitly.
On this page
Agents are for asynchronous, independent state changes. Each agent has a value plus a queue of actions. Actions are applied serially per agent, but run asynchronously on thread pools.
Use agents when:
- updates should happen in the background (logging, metrics aggregation, caches)
- state updates are independent (no multi-agent transaction/invariant)
Create and Read
1(def stats (agent {:requests 0 :errors 0}))
2
3@stats ; => {:requests 0, :errors 0}
Update with send
send queues an action (a function) to apply to the agent’s current state:
1(send stats update :requests inc)
2(send stats update :errors inc)
Actions are functions of the current state → new state.
send vs send-off
sendis intended for CPU-bound actions.send-offis intended for potentially blocking actions (I/O).
Waiting and Errors
1(await stats) ; wait for queued actions to finish
2(agent-error stats) ; => exception or nil
If an action throws, the agent enters a failed state and stops processing future actions until you handle it (for example with restart-agent).
Knowledge Check: Agents
### What does `send` do?
- [x] Queues an action function to run asynchronously and update the agent’s state.
- [ ] Mutates the agent immediately on the current thread.
- [ ] Starts a Java thread per update.
- [ ] Updates multiple agents atomically.
> **Explanation:** `send` enqueues a function to be applied to the agent’s state. Actions are processed serially for that agent.
### When should you prefer `send-off` over `send`?
- [x] When the action may block (I/O, long waits), so you don’t starve the CPU-bound pool.
- [ ] When you need atomic updates across two values.
- [ ] When you need a synchronous update.
- [ ] When you want retries like `swap!`.
> **Explanation:** `send-off` uses a separate pool intended for blocking work. It’s a safety/performance choice, not a semantic one.
### What happens if an agent action throws an exception?
- [x] The agent enters an error state and stops processing queued actions until handled.
- [ ] The exception is ignored and actions continue.
- [ ] The agent automatically retries the action until it succeeds.
- [ ] The JVM exits.
> **Explanation:** Agent failures are explicit. Check with `agent-error` and recover with `restart-agent` when appropriate.
Revised on Friday, April 24, 2026