Path 4 · lesson 2 of 5
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.
| Method | Runs when | Produces |
|---|---|---|
supplyAsync(supplier) | Now, on an executor | A future for the supplier's result |
thenApply(fn) | The previous stage completes normally | The result of a plain function of the value |
thenCompose(fn) | The previous stage completes normally | The result of the future that fn returns, flattened |
thenCombine(other, fn) | This stage and other have both completed normally | A function of the two values |
exceptionally(fn) | The previous stage completes exceptionally | A replacement value; a normal result passes through unchanged |
handle(fn) | The previous stage completes either way | A function of (value, exception), one of which is null |
orTimeout(t, unit) | The time passes and the future is still incomplete | The same future, completed with TimeoutException |
completeOnTimeout(v, t, unit) | The time passes and the future is still incomplete | The same future, completed with the value v |
thenApply is to thenCompose what map is to flatMap.Four orders, a pool of two
Simulation · not a real JVMEach 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()orjoin()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,allOfdescribe 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.
- Async method with an executor argument (
supplyAsync(fn, executor),thenApplyAsync(fn, executor)): the function is submitted to that executor. - Async method without an executor (
supplyAsync(fn),thenApplyAsync(fn)): the function is submitted to the default executor. That isForkJoinPool.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. - 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 outputavailableProcessors=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
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 outputavailableProcessors=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
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
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
thenApplywith a function that returns a future gives aCompletableFuture<CompletableFuture<Orders>>. The usual next mistake is to calljoin()on the inner one.thenComposeis the method for a step that returns a future.ordersdepends oncustomer;offerdoes 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
supplyAsyncnames theioexecutor. None of the blocking loads run on the common pool. - The lambdas passed to
thenCombineonly 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 outputexceptionally 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
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 outputslow 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"
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 tasksstays 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 outputavailableProcessors=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
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 outputavailableProcessors=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
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"]- Only the leftmost leaf is fully under your control. Reaching it takes two things: use the
Asyncvariant, 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
thenApplycan 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
- 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.
- 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.
- 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 outputpid 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
Thread dumpjcmd 4054 Thread.print: one of the two pool threads
Real JVM output4054: 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)
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 outputpid 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
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
supplyAsynctask that fans out to sub-tasks on the same executor and collects them withjoin()orallOf(...).join(). - An
@Asyncmethod that calls another@Asyncmethod of a different bean on the same executor and callsget()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.
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
TaskDecoratorcopies the logging context (trace id, user) from the submitting thread to the pool thread. Without it, log lines written onsummary-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 throwsTaskRejectedExceptionfromsupplyAsyncin the calling thread.
package com.example.summary;import java.util.List;import java.util.concurrent.CompletableFuture;import java.util.concurrent.CompletionException;import java.util.concurrent.Executor;import java.util.concurrent.TimeUnit;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.beans.factory.annotation.Qualifier;import org.springframework.stereotype.Service;@Servicepublic class OrderSummaryService { private static final Logger log = LoggerFactory.getLogger(OrderSummaryService.class); private final CustomerClient customers; private final OrderClient orders; private final OfferClient offers; private final Executor io; public OrderSummaryService(CustomerClient customers, OrderClient orders, OfferClient offers, @Qualifier("summaryIoExecutor") Executor io) { this.customers = customers; this.orders = orders; this.offers = offers; this.io = io; } public CompletableFuture<OrderSummary> summary(String customerId) { CompletableFuture<Customer> customer = CompletableFuture.supplyAsync(() -> customers.find(customerId), io); CompletableFuture<List<Order>> openOrders = customer.thenComposeAsync( c -> CompletableFuture.supplyAsync(() -> orders.openOrders(c.accountId()), io), io); CompletableFuture<Offer> offer = CompletableFuture .supplyAsync(() -> offers.bestFor(customerId), io) .completeOnTimeout(Offer.NONE, 300, TimeUnit.MILLISECONDS) .exceptionally(failure -> { log.warn("offer lookup failed for {}", customerId, unwrap(failure)); return Offer.NONE; }); return customer .thenCombine(openOrders, (c, o) -> new OrderSummary(c, o, Offer.NONE)) .thenCombine(offer, OrderSummary::withOffer) .orTimeout(2, TimeUnit.SECONDS); } private static Throwable unwrap(Throwable failure) { return failure instanceof CompletionException && failure.getCause() != null ? failure.getCause() : failure; }}Why it is written this way
- No
join()and noget()anywhere in the service. It returns the future and lets the caller decide. - Every blocking client call is inside a
supplyAsync(..., io). The functions passed tothenCombineonly build objects, so it does not matter which thread runs them. - The offer is optional:
completeOnTimeoutgives up on it after 300 ms andexceptionallycovers its failure, so a slow or broken offer service cannot fail the summary. unwrapis needed because handlers receive aCompletionExceptionaround the real cause.orTimeout(2, SECONDS)bounds the whole summary for the caller. The clients must have their own connect and read timeouts as well, because a future timeout does not free thesummary-io-thread that is still inside the call.CustomerClient,OrderClient,OfferClientand the records are assumed from the rest of the project; the clients are ordinary blocking HTTP clients.
package com.example.summary;import java.util.concurrent.CompletableFuture;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RestController;@RestControllerpublic class OrderSummaryController { private final OrderSummaryService summaries; public OrderSummaryController(OrderSummaryService summaries) { this.summaries = summaries; } @GetMapping("/customers/{id}/summary") public CompletableFuture<OrderSummary> summary(@PathVariable String id) { return summaries.summary(id); }}Why it is written this way
- Spring MVC adapts a
CompletionStagereturn value the way it handlesDeferredResult: the request thread leaves the controller at once and the response is written when the future completes. - Because the request thread is released, the
http-nio-pool is no longer the limit on concurrent summaries. Thesummary-io-pool and its queue are, which is where you want the limit to be visible. - A future that completes exceptionally reaches Spring's normal exception handling. Map
TimeoutExceptionandTaskRejectedExceptionto 504 and 503 in a@RestControllerAdvice. spring.mvc.async.request-timeoutsets a container-level timeout for the async request. Keep it above the 2 seconds in the service so that the service's timeout fires first.
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
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 thenstock.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-Nthread isWAITING (parking)inCompletableFuture.join, called from a lambda inCheckoutService, underCompletableFuture$AsyncSupply.runandThreadPoolExecutor.runWorker. There is no deadlock section, because no lock is involved.
Corrected implementation
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
thenCombinebuilds 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.
orTimeoutbounds the caller's wait. The clients still need their own timeouts so that the pool threads come back.whenCompleteis the place for compensation: if the receipt failed or timed out but the reservation succeeds, now or later, it is released.stock.thenAcceptdoes 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
TaskDecoratoror explicit parameters carry them. - Failures arrive as
CompletionExceptionand 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,
CompletableFuturecreates 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
@Asyncmethods that returnCompletableFuturewhen 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 JVMChange the pool size, the number of orders and the style. Watch which threads are parked, which are working and where the price tasks wait.
What you should see
With the blocking style and a pool of 2, none of the 4 orders finish: both threads park in join and the price tasks stay queued. That matches the real lab, which printed 0 of 4 after 3 seconds. The pool only gets through when it has more threads than orders waiting at once, so that at least one thread is left to run price tasks, and it stops again as soon as the orders catch up with the pool size. With compose, a pool of 2 finishes any number of orders because no thread waits; the real lab took 111 ms for 4. With a separate pool the waiting still costs threads, but the waiting threads and the working threads no longer compete.
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,thenCombineorallOf(...).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-Nare 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
supplyAsyncand...Asyncstage 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)orinstanceof IllegalStateExceptionnever matches, and a generic error is returned. - Cause
- Dependent stages receive a
CompletionExceptionwhose cause is the real exception. - Fix
- Unwrap once in a helper: use
ex.getCause()whenexis aCompletionExceptionwith 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
whenCompleteorexceptionallythat 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
joinframe.ThreadPoolExecutor.runWorkerbelow 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-) injoinis 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 orThread.sleepmean 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-NrunningCompletableFuture$AsyncSupplypoint 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
CompletionExceptiononly says that a stage failed. The cause is the real error; a cause ofjava.util.concurrent.TimeoutExceptioncomes fromorTimeout.
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.
thenApplymaps a value,thenComposechains a step that returns a future,thenCombinejoins two independent results.- Handlers see a
CompletionException; the real error is its cause. orTimeoutandcompleteOnTimeoutfree 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