How does Java's CompletableFuture hold its result and dependent stages internally, and what does that imply for which thread runs a callback?
answer
- one field, one linked stack
- CAS first, then pop and fire
- whoever fires it runs it
- helpers: join wakers, losing completers
- async: claim, then execute
basics
~20 sA CompletableFuture keeps one volatile result field and a Treiber stack of Completion objects. The thread that sets the result, or any thread helping it, pops and fires them, so a non-async callback has no fixed thread.
solid answer
~50 sIt has two package-private volatile fields: `result`, where null means not done and a boxed `AltResult` holds a null value or an exception, and `stack`, the head of a Treiber stack of `Completion` objects, one per dependent action or blocked waiter. `complete()` is a CAS on `result` followed by `postComplete()`, which pops each `Completion` and calls `tryFire`. So a non-async callback runs on whichever thread fires it: the completer, a thread attaching after completion, or a helper such as a thread waking from `join()`, since several threads can run `postComplete()` at once. An async stage is fired the same way, but `claim()` passes it to the executor's `execute` instead of running the function. Hence `complete()` can stall in slow callbacks, `isDone()` can be true before they have run, and neither thread identity nor sibling order is safe to rely on.
code
java · 20 linesimport java.util.concurrent.CompletableFuture;
public class WhoRunsIt {
public static void main(String[] args) throws Exception {
CompletableFuture<Integer> f = new CompletableFuture<>();
f.thenRun(() -> show("attached before completion"));
Thread completer = new Thread(() -> f.complete(1), "completer");
completer.start();
completer.join();
f.thenRun(() -> show("attached after completion"));
}
static void show(String when) {
System.out.println(when + " -> " + Thread.currentThread().getName());
}
}
// attached before completion -> completer
// attached after completion -> maingo deeper
Recall that a CompletableFuture keeps one result and a list of things to do next, and that a non-async callback runs on whichever thread fires it rather than on a fixed one.
Explain the volatile result field, the Treiber stack of Completion nodes and postComplete, then derive who runs a callback in each case: attached before completion, attached after, or helped by a thread waking from join.
Show what this does in production: a slow non-async callback stalls whichever thread completes the future, and ThreadLocal context is unreliable there. Say when you would move a stage onto an explicit executor and what a rejecting executor then does.
Weigh non-async stages, which have no hand-off cost, against losing control of the thread. A team rule such as passing an executor at every I/O boundary trades a little latency for a callback thread everyone can predict.
## The short model The source of Java's `CompletableFuture` states the design in one line: it "atomically completes by CASing a result field, and then pops off and runs those actions". A **CAS** (compare-and-set) changes a variable only if it still holds the expected value, atomically and without a lock; the file contains no `synchronized`. Because any thread can do the popping, a non-async callback has no fixed home. Everything below, apart from public methods such as `complete` and `isDone`, is package-private or private JDK 27 implementation rather than API: it explains what you observe, but it is not a promise. ## What the object holds Both fields are package-private and `volatile`: - **`result`** is an `Object`. `null` means not completed and anything else means done, which is why `isDone()` is just `result != null`. - **`AltResult`**, a package-private nested class, boxes what cannot be stored plainly: `NIL` stands for a null value, and an instance holding an exception stands for a failure. - **`stack`** is the head of a **Treiber stack**, a singly linked stack whose head changes only by CAS, so it is last in, first out. - **`Completion`**, a package-private abstract nested class, is one node. Subclasses such as `UniApply` hold the source future, the dependent future, the function and an optional executor. It extends `ForkJoinTask` and implements `Runnable`, so the same node can be handed to any executor. - **`Signaller`** is also a `Completion`: a thread that must wait in `get()` or `join()` pushes one onto the same stack and parks until it is fired. ## What happens on completion For one thread calling `complete(value)`: 1. A CAS moves `result` from `null` to the value. If two threads race, one wins and `complete` returns `false` for the other. 2. The caller runs the package-private `postComplete()`, whether or not its CAS won. 3. `postComplete()` pops the head `Completion` by CAS and calls its `tryFire`. 4. `tryFire` runs the function and completes the dependent. If that dependent has dependents of its own, the loop carries on into them instead of recursing. Other threads can be doing steps 3 and 4 at the same time, and a new stage can be attached at any point. For `thenApply`, a failed source skips the function in step 4 and the dependent simply fails too. ## Which thread runs a non-async callback The thread that gets to `tryFire` first runs the function, so the question is who gets there: | Situation | Thread that runs it | |---|---| | Attached before completion | The completing thread, inside `postComplete()` | | Attached after completion | The attaching thread, before `thenApply` returns | | Attach races with completion | The attaching thread, if `unipush`'s recheck gets there first, or a popper | | Another thread had to wait in `get()` or `join()` | Either: the waiter runs `postComplete()` on waking and helps | | Another `complete()` lost the race | Either: the losing caller runs `postComplete()` too | | Attached to an async stage still running | The thread that ran that async stage | With 20 slow callbacks and one thread parked in `join()`, the completer and that thread each run about half of them, on 27.0.1 and 25.0.3. `get()` on an already finished future does not help, because it never enters the waiting path. ## What an async variant changes An `*Async` stage is the same node with a non-null `executor`. The first thread to fire it wins `claim()`'s CAS on a tag bit from `ForkJoinTask`, clears the executor and calls `execute(this)`; the function runs later, when the executor runs the node. The no-executor stage methods use `defaultExecutor()`, which returns the private `ASYNC_POOL`, the common pool unless a subclass overrides the method. The firing thread still does part of the work: - **An inline executor** such as `Runnable::run` runs the function on the firing thread. - **A rejecting executor** makes `execute` throw inside `tryFire`'s `try`, so the dependent fails, the function never runs, and `complete` still returns `true`. - **A failed source** means `thenApplyAsync` never calls the executor at all. ## What to conclude - **Treat the thread as unknown.** A non-async callback cannot count on a `ThreadLocal` value or on being in a given pool. - **A slow callback stalls someone else's thread.** A 300 ms callback makes `complete()` return after 300 ms. - **`isDone()` does not mean callbacks finished.** `result` is set before the first pop. While a callback is still running on the completer, `isDone()` returns `true`, and a newly attached dependent runs at once on the attaching thread. - **Do not build on order.** Direct siblings can fire `third, second, first`, but the `CompletionStage` contract says dependencies "do not otherwise guarantee any particular ordering". - **A blocked pool worker may run other work.** Before parking, a `ForkJoinWorkerThread` calls the package-private `ForkJoinPool.helpAsyncBlocker`, which can run queued async completion tasks on that worker. JDK 27 passes the worker's own pool. JDK 25 at its first release passed `defaultExecutor()`, while 25.0.3 already passes the worker's pool. The public contract says less than all this: non-async actions "may be performed by the thread that completes the current CompletableFuture, or by any other caller of a completion method". Rely on that sentence.
- Can a thread that only called CompletableFuture.join() end up running a callback?Yes. If it actually had to wait, the private `waitingGet` calls `postComplete()` as it wakes, so it helps fire whatever is still on the stack. With 20 slow callbacks, the completer and the joiner each run about half. If the future was already done, `join()` reads `result` and never enters that path.
- With several threads running postComplete(), what stops a callback running twice?Two compare-and-sets. Popping moves `stack` by CAS, so one thread takes each node off the stack. A node can also be reached through `unipush`'s recheck when an attach races with completion, so before running the function, `claim()` also does a CAS on a tag bit inherited from `ForkJoinTask`. Only the winner runs the function or hands it to the executor.
- Why does a very long chain of non-async stages not overflow the thread's stack?Because `postComplete()` is a loop. In `NESTED` mode `tryFire` returns a dependent that still has work instead of calling into it, and the loop continues there, moving other branches onto its own stack. Its comment says this avoids unbounded recursion. On 27.0.1 with `-Xss512k`, a chain of 1,000,000 `thenApply` stages attached before completion finished normally.
- What happens if the executor given to thenApplyAsync rejects the task?`claim()` calls `execute` inside `tryFire`'s `try` block, so the exception is caught and the dependent completes exceptionally. The function never runs, and the caller of `complete` sees no exception. `complete` returns `true`, and the dependent's `join()` gives `RejectedExecutionException` as the cause.
- Callbacks sit in a queue and always fire in the order they were attached.
- A non-async callback always runs on the thread that called complete().
- A thread parked in join() only waits and can never run a callback.
- complete(value) only stores the value, so a slow callback cannot delay it.
- CompletableFuture guards its result and callbacks with a monitor lock.
- isDone() returning true means every dependent callback has finished.
- CompletableFuture
- Java 1.8
Assumes Java 27; these are internals, not API. The JDK 25 GA source differs only in which pool a blocked worker helps, and 25.0.3 already matches 27.
context
- CompletableFuture (Java SE 27 & JDK 27)docs.oracle.com
- CompletionStage (Java SE 27 & JDK 27)docs.oracle.com
- CompletableFuture.java at jdk-27-gagithub.com