Understanding CompletableFuture in Java 8: Overview, Features, and Source‑Code Walkthrough

CompletableFuture, introduced in JDK 1.8, extends Future and CompletionStage to enable asynchronous callbacks without blocking, offering a more elegant alternative to the older Future API.

The class was added to address the clumsy blocking or polling required by JDK 1.5's Future, allowing developers to register listeners similar to Netty's ChannelFuture for observer‑style notifications.

Key functionalities are exposed through CompletionStage methods, including transformation (thenCompose), composition (thenCombine), consumption (thenAccept), execution (thenRun), and return‑value consumption (thenApply). The difference between consumption and execution is that the former uses the result of the previous stage while the latter simply runs a task.

Example code demonstrates a simple pipeline where a task is supplied asynchronously, transformed, and followed by several thenRun/thenRunAsync calls, showing ordered execution of dependent tasks and the effect of synchronous versus asynchronous execution.

public Promise<V> addListener(GenericFutureListener<? extends Future<? super V>> listener) {
    checkNotNull(listener, "listener");
    synchronized (this) {
        addListener0(listener);
    }
    if (isDone()) {
        notifyListeners();
    }
    return this;
}

The article then dives into the source code of CompletableFuture, starting with the creation methods such as supplyAsync and the helper asyncSupplyStage, which instantiate a new CompletableFuture and schedule an AsyncSupply task on the provided executor.

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier, Executor executor) {
    return asyncSupplyStage(screenExecutor(executor), supplier);
}

The AsyncSupply#run method invokes the supplied Supplier, completes the future with the result or exception, and then triggers postComplete to fire dependent stages.

public void run() {
    CompletableFuture<T> d; Supplier<T> f;
    if ((d = dep) != null && (f = fn) != null) {
        dep = null; fn = null;
        if (d.result == null) {
            try { d.completeValue(f.get()); }
            catch (Throwable ex) { d.completeThrowable(ex); }
        }
        d.postComplete();
    }
}

Dependent stages such as thenAcceptAsync are built by creating a new CompletableFuture and linking it via a UniAccept object, which is pushed onto a stack and later fired by tryFire when the source stage completes.

public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action) {
    return uniAcceptStage(asyncPool, action);
}

The postComplete method iterates over the stack of dependent completions, popping each and invoking its tryFire method while avoiding unbounded recursion through a nested mode flag.

final void postComplete() {
    CompletableFuture<?> f = this; Completion h;
    while ((h = f.stack) != null || (f != this && (h = (f = this).stack) != null)) {
        if (f.casStack(h, h.next)) {
            CompletableFuture<?> d = h.tryFire(NESTED);
            f = d == null ? this : d;
        }
    }
}

In summary, the article provides a comprehensive walkthrough of how CompletableFuture creates, schedules, and completes asynchronous tasks, how dependent stages are registered and triggered, and why its design offers a powerful, reusable model for non‑blocking Java applications.