Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท State and Concurrency

Agents, Futures, Promises and Delays

Run work asynchronously in Clojure: agents with send and send-off, futures, promises, delays, pmap and deref with timeouts, with guidance on when to use each.

Atoms and refs change state synchronously: the call returns after the change. Clojure also has tools for asynchronous work, where you start something and collect the result later. This lesson covers agents, futures, promises and delays, plus the parallel pmap. All of them run on the JVM thread pools, and all of them return values you read with deref (@).

Agents

An agent holds state like an atom, but changes are made by sending actions to it. The action runs later, on another thread, and agents process their actions one at a time in the order sent.

CLOJURE
(def log-lines (agent []))

(send log-lines conj "started")
(send log-lines conj "working")

(await log-lines)   ; wait until queued actions are done (for tests/demos)
@log-lines          ;=> ["started" "working"]

send returns immediately. Reading with @ gives the current value, which may not yet include actions still queued. Two variants choose the thread pool:

  • send runs on a fixed pool sized for CPU-bound work.
  • send-off runs on an expandable pool and is the right choice for actions that block, such as file or network I/O.

Agents have two useful properties:

  1. Side effects are allowed, because an action runs exactly once (no retry). That makes agents a natural place for logging, file writes and notifications.
  2. Cooperation with STM: actions sent from inside a dosync transaction are held and released only if the transaction commits.

If an action throws, the agent enters a failed state and rejects further sends until you call restart-agent, or you configure :error-mode :continue with an :error-handler.

CLOJURE
(def a (agent 0 :error-mode :continue
                :error-handler (fn [ag ex] (println "failed:" (.getMessage ex)))))
(send a #(/ % 0))   ; prints the error, agent stays usable

Futures

A future runs a body on another thread and gives you a handle to the result.

CLOJURE
(def f (future (Thread/sleep 1000) (+ 1 2)))

(realized? f)   ;=> false (still running)
@f              ;=> 3     blocks until done, then returns the value
@f              ;=> 3     cached, no recompute

Dereferencing blocks the caller until the result is ready. You can pass a timeout: (deref f 500 :timed-out) waits 500 ms and returns :timed-out if nothing arrived. If the body throws, @f rethrows the exception (wrapped in an ExecutionException). future-cancel interrupts a running future.

Futures are the quickest way to overlap independent slow tasks:

CLOJURE
(let [a (future (fetch-profile id))
      b (future (fetch-orders id))]
  {:profile @a :orders @b})   ; both calls run at the same time

Futures use a thread pool that does not shut down on its own. In scripts, call (shutdown-agents) at the end, otherwise the JVM may wait about a minute before exiting.

Promises

A promise is a one-shot box you fill in later, from any thread. deref blocks until it has been delivered.

CLOJURE
(def answer (promise))

(future (Thread/sleep 500) (deliver answer 42))

@answer   ;=> 42   (blocks until delivered)
(deliver answer 99)   ; ignored: a promise accepts only one value

A promise differs from a future: a future computes its own value, while a promise is filled by someone else, which makes it a handy rendezvous between threads and a simple way to turn a callback API into a blocking one. The other difference is that a promise cannot fail by itself; if nobody delivers, a plain @ waits forever, so use (deref p ms default) in real code.

Delays

A delay postpones a computation until the first time you ask for it, then caches the result.

CLOJURE
(def config (delay (println "loading...") {:port 8080}))

@config   ; prints "loading..." then returns {:port 8080}
@config   ; returns the cached value, nothing printed
(realized? config)   ;=> true

It runs on the thread that first derefs it, exactly once, and is thread-safe, so it is ideal for expensive one-time initialization such as opening a connection or loading a file.

pmap and parallelism

(pmap f coll) is a parallel map: it applies f to elements concurrently on a thread pool and returns a lazy sequence of results in order. It pays off only when each call is slow enough (milliseconds or more) to outweigh the coordination cost.

CLOJURE
(pmap #(do (Thread/sleep 200) (* % %)) (range 8))
;; about 200 ms instead of 1600 ms on a machine with enough cores

For CPU-bound reduction over big collections, the clojure.core.reducers library (r/fold) splits work with fork/join. For small, fast functions plain map is faster than pmap.

Choosing a tool

You want to... Use
Run something in the background and get a result future
Let another thread hand you a value later promise
Compute something once, only if needed delay
Serialize updates and allow side effects, asynchronously agent
Process a list in parallel pmap
Coordinate synchronous changes to several values ref
Pipeline messages between independent workers core.async

Try it: a future and a promise with JavaScript promises

JavaScript promises are close cousins of Clojure futures. This stand-in shows start-now / read-later, timeouts and a promise that someone else delivers.

JS Future, promise, timeout

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: an agent as a serialized queue

This stand-in processes sent actions strictly one after another, in order, like a Clojure agent, even though each one is asynchronous.

JS Agent-like action queue

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which is the right choice for an action that does blocking I/O?

    send-off uses an expandable pool suited to blocking work; send uses a bounded pool for CPU-bound actions.
  2. 2. What is the main difference between a future and a promise?

    A future runs a body on another thread. A promise is an empty box another party fills once with deliver.
  3. 3. What does a delay do?

    A delay evaluates its body on first deref, exactly once, and returns the cached value afterwards.
  4. 4. How do you avoid blocking forever on a promise nobody may deliver?

    deref accepts a timeout in milliseconds and a default value to return if nothing arrives.

Summary

  • Agents apply queued actions one at a time in order; send for CPU work, send-off for blocking work; side effects are fine.
  • Futures run a body on another thread; @ blocks, with optional timeout.
  • Promises are one-shot boxes filled by deliver; delays compute once on first use.
  • pmap parallelizes slow per-item work; plain map is better for cheap functions.
  • Call shutdown-agents at the end of scripts that used them.

Next: core.async and Concurrency Patterns