Java CompletableFuture: Creation, Asynchronous Callbacks, Composition, and Thread‑Pool Configuration

1. Introduction

CompletableFuture, added to java.util.concurrent in Java 8, extends the traditional Future with stream‑style processing, functional programming support, completion notifications, and custom exception handling, making multi‑task coordination smoother.

2. Creating CompletableFuture

Three common ways to create an instance:

CompletableFuture<String> future = new CompletableFuture();
String result = future.join();
future.complete("test");

or using the static factory methods:

CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
    System.out.println("compute test");
    return "test";
});
String result = future.join();

and the runnable variant:

CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
    System.out.println("compute test");
});
System.out.println("get result: " + future.join());

3. Asynchronous Callback Methods

Key chaining functions include thenApply , thenAccept , thenRun (and their Async counterparts). The Async suffix indicates that the downstream task is submitted to a thread‑pool, otherwise it runs in the same thread that completed the previous stage.

CompletableFuture<Integer> f1 = CompletableFuture.supplyAsync(() -> 1);
CompletableFuture<Integer> f2 = f1.thenApply(p -> p + 10);
System.out.println("result: " + f2.join());

4. Exception Handling

exceptionally provides a fallback when a stage throws; whenComplete receives both result and exception for side‑effects; handle can transform the outcome and returns a new result.

CompletableFuture<Double> cf = CompletableFuture.supplyAsync(() -> {
    if (true) throw new RuntimeException("test");
    return 1.2;
});
CompletableFuture<Double> cf2 = cf.exceptionally(e -> {
    e.printStackTrace();
    return -1.1;
});

5. Task Combination

Methods that combine two independent futures:

thenCombine – combines results and returns a value.

thenAcceptBoth – consumes both results without returning.

runAfterBoth – runs after both complete, no inputs.

CompletableFuture<Integer> f1 = CompletableFuture.supplyAsync(() -> 1);
CompletableFuture<Integer> f2 = CompletableFuture.supplyAsync(() -> 10);
CompletableFuture<Integer> f3 = f1.thenCombine(f2, (a, b) -> a + b);
System.out.println("result: " + f3.join());

Similar methods applyToEither , acceptEither , and runAfterEither trigger when the first of two futures finishes.

6. Flattening with thenCompose

thenCompose eliminates nested CompletableFuture structures (similar to flatMap in streams):

CompletableFuture<Integer> f1 = CompletableFuture.supplyAsync(() -> 1);
CompletableFuture<Integer> f2 = f1.thenCompose(r -> CompletableFuture.supplyAsync(() -> r + 10));
System.out.println(f2.join());

7. allOf / anyOf

allOf completes when every supplied future finishes (throws if any fails); anyOf completes when the first finishes, returning that result.

CompletableFuture
all = CompletableFuture.allOf(cf1, cf2, cf3);
CompletableFuture
any = CompletableFuture.anyOf(cf1, cf2, cf3);

8. Implementation Details

The static supplyAsync creates a new CompletableFuture , wraps the supplied Supplier in an AsyncSupply task, and submits it to the internal asyncPool (ForkJoinPool or a per‑task executor). The run method of AsyncSupply executes the supplier, stores the result via completeValue or records an exception, then calls postComplete to trigger any dependent stages.

Each stage creates a new CompletableFuture and pushes a Completion object onto the predecessor’s stack. postComplete walks this stack, popping and executing pending completions, enabling the chain‑like behavior of CompletableFuture.

9. Thread‑Pool Configuration Guidelines

When configuring executors for CompletableFuture tasks, consider task characteristics:

CPU‑bound tasks – use a small pool (≈ cpuCount + 1 threads).

I/O‑bound tasks – use a larger pool (≈ 2 * cpuCount threads).

Mixed workloads – split into separate CPU‑ and I/O‑pools when feasible.

Prioritized work – employ PriorityBlockingQueue but beware of starvation.

Bounded queues – prevent unbounded memory growth; a few thousand slots are usually sufficient.

Choosing the right pool size and queue type improves throughput and system stability, especially when tasks involve external resources such as database connections.