Understanding CompletableFuture in Java 8: Implementation, Features, and Source‑Code Analysis

CompletableFuture, introduced in JDK 1.8, extends Future and CompletionStage to enable asynchronous callbacks and chainable operations.

Why CompletableFuture Was Introduced

JDK 1.5's Future required blocking or polling to obtain results, which is cumbersome. Registering callbacks (as in the observer pattern) avoids blocking; Netty's ChannelFuture is an example of such a callback mechanism.

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

When the task completes, addListener triggers notifyListeners.

Core Features

CompletableFuture’s power lies in its CompletionStage methods, which support:

Transformation – thenCompose Combination – thenCombine Consumption – thenAccept Execution – thenRun Consumption with return – thenApply Difference between consumption and execution: thenAccept receives the result of the previous stage, while thenRun simply runs a task without the result.

CompletableFuture can chain calls via CompletionStage methods and choose synchronous or asynchronous execution.

Simple Example

public static void thenApply() {</code>
<code>    ExecutorService executorService = Executors.newFixedThreadPool(2);</code>
<code>    CompletableFuture cf = CompletableFuture.supplyAsync(() -> {</code>
<code>        try { /* Thread.sleep(2000); */ } catch (Exception e) { e.printStackTrace(); }</code>
<code>        System.out.println("supplyAsync " + Thread.currentThread().getName());</code>
<code>        return "hello";</code>
<code>    }, executorService).thenApplyAsync(s -> {</code>
<code>        System.out.println(s + "world");</code>
<code>        return "hhh";</code>
<code>    }, executorService);
<code>    cf.thenRunAsync(() -> System.out.println("ddddd"));</code>
<code>    cf.thenRun(() -> System.out.println("ddddsd"));</code>
<code>    cf.thenRun(() -> {</code>
<code>        System.out.println(Thread.currentThread());</code>
<code>        System.out.println("dddaewdd");</code>
<code>    });
<code>}

Execution result (order may vary depending on sync/async):

supplyAsync pool-1-thread-1</code>
<code>helloworld</code>
<code>ddddd</code>
<code>ddddsd</code>
<code>Thread[main,5,main]</code>
<code>dddaewdd

Notes:

If thenRun is executed synchronously, it may run on the main thread or the thread that completed the source task.

When multiple dependent tasks exist, synchronous tasks executed by the same thread run in order, while tasks executed by the source thread are processed in LIFO order; asynchronous dependent tasks have no guaranteed order.

Source‑Code Walkthrough

Creating a CompletableFuture

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier, Executor executor) {</code>
<code>    return asyncSupplyStage(screenExecutor(executor), supplier);</code>
<code>}</code>
<code>static Executor screenExecutor(Executor e) {</code>
<code>    if (!useCommonPool && e == ForkJoinPool.commonPool()) return asyncPool;</code>
<code>    if (e == null) throw new NullPointerException();</code>
<code>    return e;</code>
<code>}

The method creates a CompletableFuture and schedules an AsyncSupply task on the provided executor.

AsyncSupply#run

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

It invokes the supplier, stores the result, and calls postComplete to trigger dependent tasks.

thenAcceptAsync creates a new dependent CompletableFuture and registers a UniAccept node.

public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action) {</code>
<code>    return uniAcceptStage(asyncPool, action);
<code>}</code>
<code>private CompletableFuture<Void> uniAcceptStage(Executor e, Consumer<? super T> f) {</code>
<code>    if (f == null) throw new NullPointerException();</code>
<code>    CompletableFuture<Void> d = new CompletableFuture<>();</code>
<code>    if (e != null || !d.uniAccept(this, f, null)) {</code>
<code>        UniAccept<T> c = new UniAccept<>(e, d, this, f);</code>
<code>        push(c); c.tryFire(SYNC);
<code>    }</code>
<code>    return d;</code>
<code>}

The UniAccept node’s tryFire eventually calls d.uniAccept, which either executes the consumer immediately (if the source task is done) or registers the node for later execution.

claim() determines whether the dependent task should run in the current thread (synchronous) or be submitted to an executor (asynchronous).

final boolean claim() {</code>
<code>    Executor e = executor;</code>
<code>    if (compareAndSetForkJoinTaskTag((short)0, (short)1)) {</code>
<code>        if (e == null) return true; // sync</code>
<code>        executor = null; // disable</code>
<code>        e.execute(this);</code>
<code>    }</code>
<code>    return false;</code>
<code>}

postComplete() iterates over the stack of dependent completions, detaches each node, and invokes tryFire (or postFire) to propagate completion without causing deep recursion.

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

When the source task finishes, postComplete triggers all registered dependent tasks, handling both synchronous and asynchronous execution paths.

Conclusion

The article dissected the internal mechanics of CompletableFuture, covering creation, asynchronous supply, dependency registration, execution modes, and the crucial postComplete flow that enables non‑blocking, chainable asynchronous programming in Java back‑end development.