Skip to content

Path 4 · lesson 2 of 5

Intermediate30 minJava 21 (OpenJDK 21) · Spring Boot 3.5 (Spring Framework 6.2)

CompletableFuture and asynchronous execution

Which thread runs each stage, how to compose calls without blocking, how errors and timeouts travel, and why join() inside a pool task can stop the pool for good.

What you will learn

  • Predict which thread runs a stage from the method used, the executor argument and whether the previous stage has completed
  • Choose thenApply, thenCompose or thenCombine for a given dependency between two calls
  • Handle failures with exceptionally and handle, and read the CompletionException that wraps the cause
  • Add timeouts with orTimeout and completeOnTimeout and say what they do not stop
  • Explain from the mechanism why join() or get() inside a pool task can leave every thread of that pool waiting for ever
  • Recognise that state in a thread dump and tell it apart from a pool that is merely busy

Before you start

The concept

A Future is a handle to a result that is not there yet, and the only thing you can do with it is wait. A CompletableFuture adds two things. Anyone can complete it, with a value or with an exception. And you can attach stages to it: functions that run when it completes and produce a new CompletableFuture. A chain of stages is a description of work, and no thread has to wait while the chain is in progress.

MethodRuns whenProduces
supplyAsync(supplier)Now, on an executorA future for the supplier's result
thenApply(fn)The previous stage completes normallyThe result of a plain function of the value
thenCompose(fn)The previous stage completes normallyThe result of the future that fn returns, flattened
thenCombine(other, fn)This stage and other have both completed normallyA function of the two values
exceptionally(fn)The previous stage completes exceptionallyA replacement value; a normal result passes through unchanged
handle(fn)The previous stage completes either wayA function of (value, exception), one of which is null
orTimeout(t, unit)The time passes and the future is still incompleteThe same future, completed with TimeoutException
completeOnTimeout(v, t, unit)The time passes and the future is still incompleteThe same future, completed with the value v
The methods this lesson uses. thenApply is to thenCompose what map is to flatMap.

Four orders, a pool of two

Simulation · not a real JVM

Each order task starts a price task on the same pool and waits for it with join(). Run it and watch what the two pool threads are doing and where the price tasks are.

Why it exists

A typical endpoint needs several remote results: the customer, the customer's open orders, a recommendation. Written with blocking calls one after another, the latency is the sum of the calls and one request thread is held for all of it. Run in parallel, the latency is close to the slowest call. CompletableFuture lets you state the dependencies (these two in parallel, this one after that one) and get the result when all of it is done.

The older way to run calls in parallel is executor.submit(...) followed by future.get(). It works, but each get() parks a thread, and a parked thread is a thread the service cannot use. When the parked thread belongs to the same pool that has to run the task it is waiting for, the wait can become permanent. That failure is the centre of this lesson, because nothing announces it: no exception, no log line, CPU at zero.

Block for the result

  • future.get() or join() in the middle of the work
  • Code reads top to bottom and exceptions have one stack trace
  • Holds a thread for the whole wait
  • Inside a pool task it makes the pool wait for itself

Compose the result

  • thenCompose, thenCombine, allOf describe what happens next
  • No thread is held while a stage is pending
  • Errors arrive wrapped, stack traces are split across threads
  • Thread-locals such as the logging context do not follow the work by themselves

How it works inside

Which thread runs a stage

There are three cases, and the method name tells you which one applies.

  1. Async method with an executor argument (supplyAsync(fn, executor), thenApplyAsync(fn, executor)): the function is submitted to that executor.
  2. Async method without an executor (supplyAsync(fn), thenApplyAsync(fn)): the function is submitted to the default executor. That is ForkJoinPool.commonPool(), unless the common pool does not support a parallelism of at least two, in which case a new thread is created for each task.
  3. Non-async method (thenApply, thenCompose, thenCombine, exceptionally, handle): no submission at all. If the previous stage is still pending, the function runs later on the thread that completes it. If the previous stage is already complete, the function runs immediately on the thread that attaches the stage.

Program outputThe same seven stages on 4 CPUs (java -XX:ActiveProcessorCount=4 CompletableFutureStages.java threads)

Real JVM output
availableProcessors=4 commonPoolParallelism=3
1 supplyAsync(supplier)                 ran on ForkJoinPool.commonPool-worker-1
2 thenApply, attached before completion ran on ForkJoinPool.commonPool-worker-1
3 thenApply, attached after completion  ran on main
4 thenApplyAsync(fn)                    ran on ForkJoinPool.commonPool-worker-1
5 thenApplyAsync(fn, io)                ran on pricing-io-1
6 supplyAsync(supplier, io)             ran on pricing-io-2
7 thenApply after an io stage           ran on pricing-io-2
Line 1: no executor given, so a common pool worker runs it. Line 2: thenApply was attached while the supplier was still sleeping, so the worker that completed the supplier ran it. Line 3: the same thenApply attached after completion ran on main, the thread that attached it. Lines 5 and 6: an explicit executor always wins. Line 7: a non-async stage after a stage on the pricing-io pool ran on that pool's thread.

Program outputThe same program on 2 CPUs (java -XX:ActiveProcessorCount=2 CompletableFutureStages.java threads)

Real JVM output
availableProcessors=2 commonPoolParallelism=1
1 supplyAsync(supplier)                 ran on Thread-0
2 thenApply, attached before completion ran on Thread-0
3 thenApply, attached after completion  ran on main
4 thenApplyAsync(fn)                    ran on Thread-1
5 thenApplyAsync(fn, io)                ran on pricing-io-1
6 supplyAsync(supplier, io)             ran on pricing-io-2
7 thenApply after an io stage           ran on pricing-io-2
With 2 available processors the common pool's parallelism is 1, so CompletableFuture does not use it. Lines 1 and 4 ran on Thread-0 and Thread-1: plain new threads, one per task, with no upper limit. A service in a container with a CPU limit of 1 or 2 gets this behaviour for every supplyAsync without an executor.

thenApply, thenCompose, thenCombine

Composition.javaJava
import java.util.concurrent.CompletableFuture;import java.util.concurrent.Executor;import java.util.concurrent.TimeUnit;public class Composition {    record Customer(String id, String tier) { }    record Orders(int open) { }    record Offer(String text) { }    record Summary(Customer customer, Orders orders, Offer offer) { }    private final Executor io;    Composition(Executor io) {        this.io = io;    }    CompletableFuture<Summary> summary(String customerId) {        CompletableFuture<Customer> customer = CompletableFuture.supplyAsync(() -> loadCustomer(customerId), io);        // thenApply: a plain function of the value. No new asynchronous work.        CompletableFuture<String> tier = customer.thenApply(Customer::tier);        // thenCompose: the next step is itself asynchronous and needs the first result.        CompletableFuture<Orders> orders = customer.thenCompose(c ->                CompletableFuture.supplyAsync(() -> loadOrders(c.id()), io));        // Independent of the customer: starts at once and runs in parallel.        CompletableFuture<Offer> offer = CompletableFuture.supplyAsync(() -> loadOffer(customerId), io)                .completeOnTimeout(new Offer("none"), 300, TimeUnit.MILLISECONDS);        // thenCombine: two results, both needed.        return customer.thenCombine(orders, (c, o) -> new Summary(c, o, null))                .thenCombine(offer, (s, f) -> new Summary(s.customer(), s.orders(), f))                .orTimeout(2, TimeUnit.SECONDS);    }    Customer loadCustomer(String id) { return new Customer(id, "gold"); }    Orders loadOrders(String customerId) { return new Orders(3); }    Offer loadOffer(String customerId) { return new Offer("free shipping"); }}

Why it is written this way

  • thenApply with a function that returns a future gives a CompletableFuture<CompletableFuture<Orders>>. The usual next mistake is to call join() on the inner one. thenCompose is the method for a step that returns a future.
  • orders depends on customer; offer does not. The offer call is started before the customer is known, so the total time is about max(customer + orders, offer), not the sum of three.
  • Every supplyAsync names the io executor. None of the blocking loads run on the common pool.
  • The lambdas passed to thenCombine only build a record. They are safe to run on whichever thread completes the second of the two inputs.
  • Compiled with javac 21.

Errors

When a stage's function throws, the stage completes exceptionally. Every stage that depends on it is skipped and completes exceptionally too, until a stage that handles failure is reached: exceptionally (failure only, like catch), handle (both outcomes, produces a new result) or whenComplete (both outcomes, keeps the original result, for logging and cleanup).

Program outputWhat handlers and callers see (java CompletableFutureStages.java errors)

Real JVM output
exceptionally on the failing stage sees: java.util.concurrent.CompletionException: java.lang.IllegalStateException: pricing service returned 503
  -> value -1
exceptionally one stage later sees:      java.util.concurrent.CompletionException: java.lang.IllegalStateException: pricing service returned 503
  getCause():                            java.lang.IllegalStateException: pricing service returned 503
  -> value -1
handle((value, ex) -> ...) returns:      failed: pricing service returned 503
join() with no handler throws:           java.util.concurrent.CompletionException: java.lang.IllegalStateException: pricing service returned 503
get() with no handler throws:            java.util.concurrent.ExecutionException: java.lang.IllegalStateException: pricing service returned 503
The supplier threw IllegalStateException, but both exceptionally handlers received a CompletionException whose getCause() is the real exception. Code that tests ex instanceof IllegalStateException in a handler is therefore wrong; unwrap the cause first. The last two lines show the difference at the end of the chain: join() throws the unchecked CompletionException, get() throws the checked ExecutionException, both with the same cause.

Timeouts

orTimeout and completeOnTimeout exist since Java 9. Both complete the future if it is still pending after the given time. Neither stops the work: CompletableFuture has no control over the computation that will complete it, and cancel(true) does not interrupt anything either. The Javadoc of cancel says its argument has no effect in this implementation.

Program outputA 1,000 ms call with 200 ms timeouts (java CompletableFutureStages.java timeout)

Real JVM output
slow supplier takes 1000 ms, both timeouts are 200 ms
t= 205 ms  orTimeout fired: java.util.concurrent.TimeoutException (on CompletableFutureDelayScheduler)
t= 207 ms  orTimeout + exceptionally returned "cached price"
t= 407 ms  completeOnTimeout returned "default price"
t= 408 ms  the original future isDone=false
t=1004 ms  the slow supplier finished anyway on Thread-0
t=1208 ms  the original future isDone=true value="live price"
At 205 ms orTimeout completed the future with TimeoutException and the exceptionally fallback returned the cached price. Look at the thread: the fallback ran on CompletableFutureDelayScheduler, a single JDK thread shared by every timeout in the JVM, so a slow fallback there delays all other timeouts. At 1,004 ms the slow supplier finished anyway: its thread was occupied for the full second although nobody was waiting for the result. A future timeout protects the caller. Only a timeout inside the call itself, such as an HTTP read timeout, frees the thread.

Why join() inside a pool task starves the pool

A pool task that submits a second task to the same pool and then calls join() on it holds a thread while it waits for work that needs a thread. As long as a spare thread exists, the inner task runs and the outer one continues. When enough outer tasks are running to occupy every thread, each of them is parked waiting for an inner task, every inner task is in the queue, and no thread will ever become free to take one. The pool is not slow; it has stopped.

  • It needs no lock, so the JVM's deadlock detector does not report it. The thread dump has no "Found one Java-level deadlock" section.
  • It depends on concurrency. With a pool of 16 it needs 16 outer tasks in flight at once, so it passes every test and appears at the first real traffic peak.
  • An unbounded queue hides it further: submissions keep succeeding and the queue grows while completed tasks stays constant.
  • A larger pool only raises the load at which it happens. The fix is structural: do not wait, or wait on a different pool.

Why blocking I/O does not belong on the common pool

The common pool is one pool for the whole JVM. Parallel streams use it, supplyAsync without an executor uses it, and so does any library that does the same. It is sized for CPU-bound work: on OpenJDK 21 its parallelism was 3 with 4 available processors and 1 with 2 in the runs above, one less than the processor count. A handful of tasks blocked on a database or an HTTP call occupy all of it.

Program output12 blocking calls of 200 ms, 4 CPUs (java -XX:ActiveProcessorCount=4 CompletableFutureStages.java blocking)

Real JVM output
availableProcessors=4 commonPoolParallelism=3
12 blocking calls of 200 ms on the default executor: 808 ms
12 blocking calls of 200 ms on a dedicated pool of 12: 203 ms
Twelve calls that each wait 200 ms took 808 ms on the default executor: 3 workers, so 4 rounds of 200 ms. On a dedicated pool of 12 threads the same calls took 203 ms. While those 808 ms pass, every parallel stream and every other supplyAsync in the process waits for the same 3 workers.

Program outputThe same on 2 CPUs (java -XX:ActiveProcessorCount=2 CompletableFutureStages.java blocking)

Real JVM output
availableProcessors=2 commonPoolParallelism=1
12 blocking calls of 200 ms on the default executor: 207 ms
12 blocking calls of 200 ms on a dedicated pool of 12: 201 ms
On 2 CPUs the default executor finished in 207 ms. That is not good news: with a common pool parallelism of 1, each task got its own new thread. Twelve calls made 12 threads; 5,000 concurrent calls would try to make 5,000. The behaviour of the same line of code changes with the container's CPU limit, which is one more reason to always pass an executor.

Architecture

Drawing diagram…

Flowchart. An async method with an executor argument is submitted to that executor. An async method without one goes to the common ForkJoinPool when its parallelism is at least two, otherwise to a new thread per task. A non-async method runs on the attaching thread if the previous stage is already complete, and otherwise on whichever thread completes the previous stage.

flowchart TD
  A["A stage is attached to a future"] --> B{"Method name ends in Async"}
  B -->|"Yes"| C{"Executor argument given"}
  C -->|"Yes"| D["Submitted to that executor"]
  C -->|"No"| E{"Common pool parallelism is 2 or more"}
  E -->|"Yes"| F["Submitted to ForkJoinPool.commonPool"]
  E -->|"No"| G["A new thread for each task"]
  B -->|"No"| H{"Previous stage already complete"}
  H -->|"Yes"| I["Runs now on the thread that attaches the stage"]
  H -->|"No"| J["Runs later on the thread that completes the previous stage"]
How CompletableFuture picks the thread for a stage in JDK 21.
  • Only the leftmost leaf is fully under your control. Reaching it takes two things: use the Async variant, and pass an executor.
  • The two leaves under "No executor" are decided by the machine, not the code: the number of available processors when the JVM starts.
  • The two leaves on the right are decided by timing. The same thenApply can run on a pool worker in one request and on the calling thread in the next, as lines 2 and 3 of the real output show.
  • For a short, pure function none of this matters. It matters when the function blocks, takes a lock, uses a thread-local, or is slow.

Step by step

Drawing diagram…

Sequence diagram. The request thread submits four order tasks to a pool with two threads. Each thread takes one order, submits a price task to the same pool's queue and parks in join waiting for it. The queue now holds two orders and two prices, and no thread is free to run them. The request thread times out after three seconds with none of the four orders finished.

sequenceDiagram
  participant R as Request thread
  participant Q as Pool queue
  participant A as Pool thread 1
  participant B as Pool thread 2
  R->>Q: submit order 1, 2, 3 and 4
  Q-->>A: order 1
  Q-->>B: order 2
  A->>Q: submit price 1
  Note over A: Parks in join waiting for price 1
  B->>Q: submit price 2
  Note over B: Parks in join waiting for price 2
  Note over Q: Holds order 3, order 4, price 1 and price 2
  Note over A,B: No thread is left to take price 1 or price 2
  R->>Q: allOf get with a 3 second timeout
  Q-->>R: TimeoutException with 0 of 4 orders done
A pool of two threads waiting for tasks that sit in its own queue.
  1. Both pool threads are parked, and both are waiting for something that only a pool thread can do. There is no third party that could break the wait.
  2. The queue order makes it worse: orders 3 and 4 are ahead of prices 1 and 2. Even if one thread became free it would start another order, which would park as well.
  3. The request thread is the only one with a timeout. It gives up after 3 seconds, but the two pool threads stay parked until the process ends.

In a real system

The lab is the smallest version of this failure: a pool of 2 threads and 4 orders. Each order task prices itself by starting a price task on the same pool and calling join().

Program outputjava CfStarvation.java blocking

Real JVM output
pid 4054, mode blocking, pool of 2 threads, 4 orders
TIMEOUT after 3 s: 0 of 4 orders finished. Both pool threads are waiting in join() for price tasks that sit in the pool's own queue.
The process will now stay up for 60 s so you can take a thread dump: jcmd 4054 Thread.print
0 of 4 orders finished. A price task takes 50 ms, so with working composition all four would be done in about 100 ms. There is no exception and no error output: the only reason anything was printed is the 3 second timeout the main thread put on its own wait.

Thread dumpjcmd 4054 Thread.print: one of the two pool threads

Real JVM output
4054:
2026-11-15 21:24:39
Full thread dump OpenJDK 64-Bit Server VM (21.0.13+9-LTS mixed mode, sharing)
...
"order-pool-19" #19 [4074] daemon prio=5 os_prio=0 cpu=0.11ms elapsed=5.74s tid=0x00007384bc58a9a0 nid=4074 waiting on condition  [0x00007384957fd000]
   java.lang.Thread.State: WAITING (parking)
	at jdk.internal.misc.Unsafe.park(java.base@21.0.13/Native Method)
	- parking to wait for  <0x00000000f7183c30> (a java.util.concurrent.CompletableFuture$Signaller)
	at java.util.concurrent.locks.LockSupport.park(java.base@21.0.13/LockSupport.java:221)
	at java.util.concurrent.CompletableFuture$Signaller.block(java.base@21.0.13/CompletableFuture.java:1864)
	at java.util.concurrent.ForkJoinPool.unmanagedBlock(java.base@21.0.13/ForkJoinPool.java:3780)
	at java.util.concurrent.ForkJoinPool.managedBlock(java.base@21.0.13/ForkJoinPool.java:3725)
	at java.util.concurrent.CompletableFuture.waitingGet(java.base@21.0.13/CompletableFuture.java:1898)
	at java.util.concurrent.CompletableFuture.join(java.base@21.0.13/CompletableFuture.java:2117)
	at CfStarvation.lambda$main$2(CfStarvation.java:33)
	at CfStarvation$Lambda/0x0000738448164428.get(Unknown Source)
	at java.util.concurrent.CompletableFuture$AsyncSupply.run(java.base@21.0.13/CompletableFuture.java:1768)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(java.base@21.0.13/ThreadPoolExecutor.java:1144)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(java.base@21.0.13/ThreadPoolExecutor.java:642)
	at java.lang.Thread.runWith(java.base@21.0.13/Thread.java:1596)
	at java.lang.Thread.run(java.base@21.0.13/Thread.java:1583)
Read it from the bottom. ThreadPoolExecutor$Worker.run and runWorker: this is a pool worker that is running a task, not an idle one (an idle worker would be in getTask). CompletableFuture$AsyncSupply.run: the task is a supplyAsync supplier. CfStarvation.lambda$main$2(CfStarvation.java:33): the application line that blocks. CompletableFuture.join and WAITING (parking) on a CompletableFuture$Signaller: it waits for another future. cpu=0.11ms after elapsed=5.74s: it has done nothing. The second pool thread, order-pool-20, has the identical stack. Two of two workers parked in join() under AsyncSupply.run is the whole diagnosis. The ForkJoinPool.managedBlock frames are how join parks on any thread; they do not mean a ForkJoinPool is involved.

Program outputjava CfStarvation.java composed

Real JVM output
pid 4120, mode composed, pool of 2 threads, 4 orders
order 1 costs 101
order 2 costs 102
order 3 costs 103
order 4 costs 104
finished in 111 ms
The same pool of 2 and the same 4 orders, with thenCompose in place of join(): finished in 111 ms. No thread waits for another task, so two threads are enough.

In a real service the shape is the same and the numbers are larger. The usual ways to arrive there:

  • A supplyAsync task that fans out to sub-tasks on the same executor and collects them with join() or allOf(...).join().
  • An @Async method that calls another @Async method of a different bean on the same executor and calls get() on the result.
  • A task that calls a client library which internally submits to the application's shared executor and blocks for the answer.
  • A listener or scheduler pool whose tasks wait on futures completed by the same pool.

The production signature is always the same four observations: requests hang rather than fail, CPU is near zero, the executor's queue grows while its completed count stands still, and the dump shows every worker of one pool parked in CompletableFuture.join or FutureTask.get beneath that pool's own runWorker. The Practice case requests that never return trains the same reading on a lock deadlock; the difference here is that the dump has no deadlock section to point you at it.

Java and Spring Boot

An order summary endpoint in Spring Boot 3.5: three blocking client calls composed on a dedicated, bounded executor, with the request thread released while they run. Written against Spring Boot 3.5 and Spring Framework 6.2; not compiled against Spring here.

src/main/java/com/example/summary/AsyncConfig.javaJava
package com.example.summary;import java.util.Map;import org.slf4j.MDC;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.core.task.TaskDecorator;import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;@Configurationpublic class AsyncConfig {    /** Blocking client calls only. CPU-bound work and waiting on other futures do not belong here. */    @Bean    public ThreadPoolTaskExecutor summaryIoExecutor() {        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();        executor.setThreadNamePrefix("summary-io-");        executor.setCorePoolSize(32);        executor.setMaxPoolSize(32);        executor.setQueueCapacity(64);        executor.setTaskDecorator(copyLoggingContext());        executor.setWaitForTasksToCompleteOnShutdown(true);        executor.setAwaitTerminationSeconds(10);        return executor;    }    private static TaskDecorator copyLoggingContext() {        return task -> {            Map<String, String> context = MDC.getCopyOfContextMap();            return () -> {                if (context != null) {                    MDC.setContextMap(context);                }                try {                    task.run();                } finally {                    MDC.clear();                }            };        };    }}

Why it is written this way

  • A named, bounded pool for one kind of work. 32 threads cover about 100 summaries per second with three calls of roughly 100 ms each: 100 × 3 × 0.1 = 30 busy threads.
  • The TaskDecorator copies the logging context (trace id, user) from the submitting thread to the pool thread. Without it, log lines written on summary-io- threads lose their request id.
  • The decorator covers tasks submitted to this executor. A non-async stage that happens to run on another thread does not pass through it.
  • The default handler is AbortPolicy: a full queue throws TaskRejectedException from supplyAsync in the calling thread.

Wrong, then right

A checkout service prices a cart and reserves stock in parallel, then builds a receipt. It uses one executor of 16 threads for everything. Both versions are plain Java apart from the annotations; they were compiled with javac 21 against stand-in annotations and client interfaces, not against Spring.

Incorrect implementation

src/main/java/com/example/checkout/CheckoutService.javaJava
package com.example.checkout;import java.util.concurrent.CompletableFuture;import java.util.concurrent.Executor;import org.springframework.beans.factory.annotation.Qualifier;import org.springframework.stereotype.Service;@Servicepublic class CheckoutService {    private final PricingClient pricing;    private final InventoryClient inventory;    private final Executor checkoutExecutor;      // 16 threads, unbounded queue    public CheckoutService(PricingClient pricing, InventoryClient inventory,                           @Qualifier("checkoutExecutor") Executor checkoutExecutor) {        this.pricing = pricing;        this.inventory = inventory;        this.checkoutExecutor = checkoutExecutor;    }    public CompletableFuture<Receipt> checkout(Cart cart) {        return CompletableFuture.supplyAsync(() -> {            CompletableFuture<Price> price =                    CompletableFuture.supplyAsync(() -> pricing.price(cart), checkoutExecutor);            CompletableFuture<Reservation> stock =                    CompletableFuture.supplyAsync(() -> inventory.reserve(cart), checkoutExecutor);            return new Receipt(cart.id(), price.join(), stock.join());   // waits on its own pool        }, checkoutExecutor);    }}

Why it is written this way

  • The outer task and the two inner tasks all run on checkoutExecutor.
  • The outer task holds a pool thread while it is parked in price.join() and then stock.join().
  • Each checkout therefore needs up to three threads of the same pool at once: one that only waits, two that work.
  • It looks parallel and it passes tests, because one checkout at a time always finds spare threads.

Why it fails

  • Each checkout occupies one thread that does nothing but wait. With 16 threads, the pool stops for good as soon as 16 checkouts are in their outer task at the same moment: all 16 threads are parked in join(), all 32 inner tasks are in the queue, and no thread can ever take one.
  • Before that point the service is already paying for it. Every waiting outer task removes a thread, so a pool of 16 behaves like a much smaller one and latency rises earlier than the sizing predicts.
  • Nothing fails visibly. The queue is unbounded, so new checkouts are accepted and queue behind work that will never finish. No exception is thrown, CPU drops to zero, and the health check stays green.
  • It does not recover when traffic falls. The parked threads have no timeout, so only a restart frees them, and the restart loses every queued checkout.
  • In the thread dump every checkout-exec-N thread is WAITING (parking) in CompletableFuture.join, called from a lambda in CheckoutService, under CompletableFuture$AsyncSupply.run and ThreadPoolExecutor.runWorker. There is no deadlock section, because no lock is involved.

Corrected implementation

src/main/java/com/example/checkout/CheckoutService.javaJava
package com.example.checkout;import java.util.concurrent.CompletableFuture;import java.util.concurrent.Executor;import java.util.concurrent.TimeUnit;import org.springframework.beans.factory.annotation.Qualifier;import org.springframework.stereotype.Service;@Servicepublic class CheckoutService {    private final PricingClient pricing;    private final InventoryClient inventory;    private final Executor checkoutExecutor;      // 16 threads, bounded queue    public CheckoutService(PricingClient pricing, InventoryClient inventory,                           @Qualifier("checkoutExecutor") Executor checkoutExecutor) {        this.pricing = pricing;        this.inventory = inventory;        this.checkoutExecutor = checkoutExecutor;    }    public CompletableFuture<Receipt> checkout(Cart cart) {        CompletableFuture<Price> price =                CompletableFuture.supplyAsync(() -> pricing.price(cart), checkoutExecutor);        CompletableFuture<Reservation> stock =                CompletableFuture.supplyAsync(() -> inventory.reserve(cart), checkoutExecutor);        return price                .thenCombine(stock, (p, s) -> new Receipt(cart.id(), p, s))                .orTimeout(2, TimeUnit.SECONDS)                .whenComplete((receipt, failure) -> {                    if (failure != null) {                        stock.thenAccept(inventory::release);   // undo a reservation that did succeed                    }                });    }}

Why it is written this way

  • There is no outer task. The two calls are submitted directly and thenCombine builds the receipt when both are done. No thread waits for another task.
  • A checkout now uses exactly two pool threads, and only while each is doing real work. Sixteen threads serve eight checkouts at once at full speed, and more simply queue.
  • orTimeout bounds the caller's wait. The clients still need their own timeouts so that the pool threads come back.
  • whenComplete is the place for compensation: if the receipt failed or timed out but the reservation succeeds, now or later, it is released. stock.thenAccept does nothing if the reservation itself failed.
  • If a blocking wait cannot be avoided, the wait must happen on a different pool from the one that runs the awaited work, so that a waiting thread never occupies a working thread's slot.

Trade-offs

  • The control flow is no longer one method read top to bottom. A stack trace shows only the stage that failed, not the request that started it, so logging needs a request id that travels with the work.
  • Thread-locals do not follow stages. The logging context, the security context and a transaction bound to the calling thread are absent on the pool thread unless a TaskDecorator or explicit parameters carry them.
  • Failures arrive as CompletionException and have to be unwrapped; a timeout no longer means the work stopped, so compensation such as releasing the reservation has to be written by hand.
  • The combining function runs on whichever pool thread finishes second. It must stay short and must not block, or it brings the original problem back in a smaller form.
  • On Java 21 there is another option for I/O-bound work: keep the blocking style and run each task on a virtual thread, where a parked thread is cheap. That has its own limits, covered in the virtual threads lesson.

Configuration

CompletableFuture itself has no settings; timeouts are per call. These are the settings that decide where its stages run. Defaults are from the Java SE 21 API documentation and the Spring Boot 3.5 properties reference.

java.util.concurrent.ForkJoinPool.common.parallelismDefault not stated in the Javadoc; OpenJDK 21 used available processors minus 1, at least 1, in the runs above
What it does
System property for the parallelism of the common pool, which is the default executor of async stages when it is 2 or more. Below 2, CompletableFuture creates a thread per task instead.
When to change it
Do not raise it to make room for blocking calls. Pass your own executor for I/O and leave the common pool to CPU-bound work. Log ForkJoinPool.getCommonPoolParallelism() at start-up so you know which behaviour a small container gets.
java.util.concurrent.ForkJoinPool.common.maximumSparesDefault 256
What it does
The maximum number of extra threads the common pool may add to maintain its target parallelism while workers are blocked in ways the pool manages.
When to change it
Leave it alone. The Javadoc states that no such compensation is guaranteed for blocked I/O, so it is not a safety net for blocking calls on the common pool.
spring.mvc.async.request-timeoutDefault none (the default timeout of the underlying servlet container is used)
What it does
Amount of time before asynchronous request handling times out, which applies to controllers that return a CompletableFuture.
When to change it
Set it explicitly and a little above the timeout on the future itself, so that the application's own timeout produces the error response.
spring.task.execution.pool.queue-capacityDefault none listed (unbounded)
What it does
Queue capacity of Spring Boot's auto-configured executor, which runs @Async methods that return CompletableFuture when no other executor is named.
When to change it
An unbounded queue is what lets a starved pool keep accepting work silently. Bound it, as in the previous lesson.

Hands-on exercise

Starve a pool, then compose

Reproduce the pool that waits for itself, find out how the pool size and the number of orders decide whether it stops, and compare the two fixes.

Steps · 0 of 6 done

Orders that price themselves on their own pool

Simulation · not a real JVM

Change the pool size, the number of orders and the style. Watch which threads are parked, which are working and where the price tasks wait.

Take it further in the simulation: CompletableFuture starvation: a pool waiting for itself

What can go wrong

join() or get() inside a task of the same pool
Symptom
Under a traffic peak requests hang for ever. CPU is near zero, the executor queue grows and its completed count does not move.
Cause
Every pool thread holds an outer task parked on an inner task that is queued behind it on the same pool.
Fix
Compose with thenCompose, thenCombine or allOf(...).thenApply(...). If you must block, block on a thread of a different pool and always with a timeout.
supplyAsync without an executor for blocking calls
Symptom
Parallel streams and unrelated async code slow down whenever a database or HTTP dependency is slow. Threads named ForkJoinPool.commonPool-worker-N are in socket reads.
Cause
The default executor is the JVM-wide common pool, sized for CPU work with about one thread per processor.
Fix
Pass a dedicated, bounded executor to every supplyAsync and ...Async stage that does I/O.
Thread per task in a small container
Symptom
The thread count climbs into the thousands during a slowdown, with threads named Thread-N, and the process may fail with an error creating native threads.
Cause
With 1 or 2 available processors the common pool's parallelism is below 2, so each async task without an executor gets a new thread, without limit.
Fix
Always pass an executor. Check ForkJoinPool.getCommonPoolParallelism() in the environment the service runs in, not on a laptop.
Treating orTimeout as cancellation
Symptom
After adding orTimeout, callers get fast errors but the pool stays saturated and the downstream service stays overloaded.
Cause
The timeout completes the future only. The task keeps its thread until the underlying call returns, and cancel(true) does not interrupt it.
Fix
Put connect and read timeouts on the client itself. Use the future timeout as the caller's bound, not as the resource bound.
Checking the exception type without unwrapping
Symptom
A handler written as if (ex instanceof TimeoutException) or instanceof IllegalStateException never matches, and a generic error is returned.
Cause
Dependent stages receive a CompletionException whose cause is the real exception.
Fix
Unwrap once in a helper: use ex.getCause() when ex is a CompletionException with a cause.
A failed future that nobody looks at
Symptom
A background step silently stops having an effect. Nothing is logged.
Cause
An exceptional completion is stored in the future. If no stage handles it and nobody calls join(), it is never reported.
Fix
End every chain that is not returned to a caller with whenComplete or exceptionally that logs the unwrapped cause.

How to troubleshoot

Requests hang, CPU is near zero

Check

jcmd <pid> Thread.print > dump.txt, then grep -B 9 -A 6 'CompletableFuture.join\|FutureTask.get' dump.txt
How to read it
Look at what is below the join frame. ThreadPoolExecutor.runWorker below it means a pool thread is waiting on a future. If all threads of one pool look like that, the pool is waiting for itself. A request thread (http-nio-) in join is only a caller waiting.
Not sure whether a pool is busy or stuck

Check

Micrometer `executor.completed`, `executor.active` and `executor.queued` for the executor (tag `name`), sampled twice a few seconds apart
How to read it
Active equal to pool size with a completed count that rises is a busy pool. Active equal to pool size with a completed count that does not change is a stuck pool.
Suspect blocking work on the common pool

Check

grep -A 12 '"ForkJoinPool.commonPool-worker-' dump.txt
How to read it
Common pool workers should be computing or idle. Workers in SocketDispatcher.read0, a JDBC driver or Thread.sleep mean blocking calls were submitted without an executor.
Thread count grows without limit

Check

Micrometer `jvm.threads.live`, and grep -c '^"Thread-' dump.txt
How to read it
Many threads named Thread-N running CompletableFuture$AsyncSupply point at thread-per-task execution: async stages without an executor on a JVM whose common pool parallelism is 1.
Need to know which default executor this JVM uses

Check

jshell -R-XX:ActiveProcessorCount=2, then java.util.concurrent.ForkJoinPool.getCommonPoolParallelism()
How to read it
2 or more: async stages without an executor share the common pool. 1: each one gets a new thread. Use the processor count of the production container.
java.util.concurrent.CompletionException in the logs

Check

Read the `Caused by:` section of the stack trace, or log `ex.getCause()`
How to read it
CompletionException only says that a stage failed. The cause is the real error; a cause of java.util.concurrent.TimeoutException comes from orTimeout.

Key takeaways

  • Every stage runs on a thread. Async methods with an executor run where you say; without one they use the common pool, or a new thread per task on a JVM with fewer than 3 processors.
  • A non-async stage runs on the thread that completes the previous stage, or on the attaching thread if it is already complete. Keep such stages short.
  • thenApply maps a value, thenCompose chains a step that returns a future, thenCombine joins two independent results.
  • Handlers see a CompletionException; the real error is its cause.
  • orTimeout and completeOnTimeout free the caller, not the thread doing the work. The call itself needs a timeout.
  • A pool task that blocks on a task of the same pool stops the pool once enough of them run at once. Compose, or wait on a different pool.
  • Blocking I/O belongs on a dedicated, bounded executor, never on the common pool.

Practical check

Small scenarios, one decision each. Pick what you would do, then read why.

Scenario 1 of 4

A service on an 8-CPU host loads reports with CompletableFuture.supplyAsync(() -> reportDao.load(id)) and no executor. Each load is a JDBC query of about 2 seconds. When 20 reports are requested together, an unrelated feature that uses list.parallelStream() becomes slow at the same time.

What explains the slow parallel stream, and what is the fix?

Scenario 2 of 4

findUser(id) returns CompletableFuture<User> and findOrders(userId) returns CompletableFuture<List<Order>>. A developer writes findUser(id).thenApply(u -> findOrders(u.id())) and, to get rid of the nested type, adds .thenApply(f -> f.join()). Both lookups run on the same 8-thread executor.

Which change is correct?

Scenario 3 of 4

Checkout requests hang. CPU is at 1 percent. Micrometer shows executor.active = 16 of 16 for checkoutExecutor, executor.queued = 340 and rising, executor.completed unchanged for two minutes. All 16 checkout-exec threads are WAITING in CompletableFuture.join under AsyncSupply.run.

What is the right response?

Scenario 4 of 4

To protect an endpoint, a team adds .orTimeout(500, MILLISECONDS) to a supplyAsync call that fetches prices over HTTP on a 20-thread executor. The HTTP client has no read timeout. During a pricing outage the endpoint now answers in 500 ms with an error, but executor.active stays at 20 and the queue keeps growing.

Why is the pool still saturated?

References

References: Java SE 21 API: CompletableFuture (execution policies, orTimeout, completeOnTimeout, cancel) ↗ · Java SE 21 API: CompletionStage (thenApply, thenCompose, thenCombine, exceptional completion) ↗ · Java SE 21 API: ForkJoinPool (the common pool and its system properties, blocking) ↗ · Java SE 21 tool reference: jcmd (Thread.print) ↗ · Spring Framework 6.2 reference: Spring MVC asynchronous requests ↗ · Spring Framework 6.2 reference: Task Execution and Scheduling (@Async, TaskDecorator) ↗ · Spring Boot 3.5: Common Application Properties (spring.mvc.async.request-timeout, spring.task.execution.*) ↗ · Report a problem