How Does CompletableFuture Chain Async Work?

A CompletableFuture is a Future that can be completed by hand and, crucially, that can have continuations attached. Instead of blocking a thread waiting for a result and then starting the next step, you describe the next step as a function and the runtime runs it when the result arrives.

The chain is built from the then-style methods. thenApply transforms a result, thenAccept consumes it and returns another CompletableFuture, thenCompose flattens a nested future, and thenCombine waits for two futures and joins their results. Each returns a new CompletableFuture, so the steps compose into a pipeline.

There are three ways to start the work, and the difference is where the code runs. supplyAsync and runAsync run a supplier on the common ForkJoinPool. completedFuture gives you an already-finished future. And the plain thenApply runs its function on whichever thread completed the previous stage — so if that was an IO thread, your transformation runs on the IO thread too.

That last point is why the Async variants exist. thenApplyAsync moves the continuation onto the executor rather than running it inline, which is what you want when the continuation is slow, or when you want to keep the completing thread free. And you can pass your own executor to thenApplyAsync so the work lands on a pool you control rather than the shared common pool.

There are three ways to get one. completedFuture(value) gives you a future that is already finished. supplyAsync(supplier) runs the supplier on the common pool and completes the future with its result. And new CompletableFuture<>() gives you one you complete yourself, which is what you use when the result comes from a callback — an HTTP client, a message listener, a database callback.

import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        // Already complete.
        CompletableFuture<String> ready = CompletableFuture.completedFuture("ready");
        System.out.println("completed : " + ready.join());

        // Completed by hand.
        CompletableFuture<String> manual = new CompletableFuture<>();
        manual.complete("completed later");
        System.out.println("manual    : " + manual.join());

        // Built from a supplier, running on the common pool.
        CompletableFuture<String> supplied = CompletableFuture.supplyAsync(() -> {
            sleepQuietly(30);
            return "computed asynchronously";
        });
        System.out.println("supplied  : " + supplied.join());

        // Chained transformations.
        CompletableFuture<Integer> length = CompletableFuture
                .supplyAsync(() -> "tutorsbot")
                .thenApply(String::length);
        System.out.println("length    : " + length.join());
    }

    static void sleepQuietly(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }
}

The output shows all four ways. The already-complete future returns immediately. The manual one returns once you complete it. The supplied one runs on the pool. And the chained pipeline computes the length of a string that was produced asynchronously.

Two notes on consuming a future. join waits for the result and wraps any failure in a CompletionException, while get is the blocking Future method and wraps failures in an ExecutionException. Both block the calling thread, so in a request handler you usually want to return the future to the framework rather than joining it. And a future completed exceptionally carries the failure to the end of the chain, where exceptionally, handle or whenComplete can deal with it.

All three continue a chain, and they differ on two axes: whether the continuation runs on the completing thread or on a pool, and whether the result is flattened.

thenApply runs its function inline, on whichever thread completed the previous stage, and it returns a future of the transformed value. Use it for a cheap transformation that you do not mind running on the completing thread.

thenApplyAsync runs the function on the common pool, or on an executor you pass in. The important difference in practice is that the completing thread is freed immediately. If the completing thread is an IO thread, thenApply blocks that IO thread while your transformation runs — which is exactly the kind of thing that starves an event loop or a connection pool.

thenCompose is the flattening variant. Where thenApply given a function returning a CompletableFuture produces a future of a future, thenCompose unwraps it and gives you a single future. It is the equivalent of flatMap, and it is what you need whenever a stage calls another asynchronous API.

The distinction that catches people out is between thenApply and thenCompose. If your function returns a plain value, use thenApply. If it returns a CompletableFuture, use thenCompose — using thenApply there leaves you with a CompletableFuture of a CompletableFuture and forces you to unwrap it by hand.

One more practical tool worth knowing: allOf takes several futures and returns a future that completes when all of them are done, and anyOf completes when the first one is. They are how you fan out and then join.