CompletableFuture

A CompletableFuture isn't always finished automatically — you can finish it yourself. complete(value) makes it succeed with that value; completeExceptionally(ex) makes it fail with that exception. Both return true only if your call was the one that completed it.

Use CompletableFuture.supplyAsync when the task returns a value, and runAsync when it returns nothing. supplyAsync takes a Supplier and gives a CompletableFuture<T>; runAsync takes a Runnable and gives a CompletableFuture<Void>.

thenApply transforms the result into a new value (map). thenAccept consumes the result but returns nothing. thenRun runs an action that ignores the result entirely. All three run after the stage completes.

thenApply may run the callback on whatever thread completed the previous stage (or the caller). thenApplyAsync hands the callback to a separate thread pool to run, so it does not block the completing thread.

Both block until the result is ready. get() throws checked exceptions (InterruptedException, ExecutionException), so callers must handle them. join() throws unchecked exceptions (CompletionException), so it's cleaner inside lambdas and stream pipelines.

By default they run on the shared ForkJoinPool.commonPool(). Each async method also has an overload that takes an Executor, so you pass your own thread pool as a second argument to control where the task runs.

If a stage throws, the future completes exceptionally and later stages are skipped until an error-handling callback. The original exception is usually wrapped in a CompletionException, so you often unwrap it via getCause().

exceptionally runs only on failure and supplies a fallback value. handle runs on both success and failure and returns a new value. whenComplete runs on both for a side-effect (like logging) but cannot change the result.

When you don't pass an executor, callbacks run on the shared ForkJoinPool.commonPool, which has only a few threads. Blocking those threads starves every other task using that pool. Fix it by passing your own dedicated executor to the *Async methods.

If a stage throws and you never call join()/get() and never add exceptionally()/handle(), the failure is stored inside the future and nobody ever sees it — no log, no crash. Always terminate a chain by either joining it or attaching an error handler.

Use thenApply when your function returns a plain value. Use thenCompose when your function itself returns another CompletableFuture, so you chain asynchronous steps without ending up with a CompletableFuture wrapped inside a CompletableFuture.

The no-executor *Async methods use one small shared ForkJoinPool for the whole JVM. Blocking it (I/O, waits) starves every other user of that pool. Pass your own executor sized for blocking work instead.

allOf can take futures of different types, so it can't return one combined value — it returns Void, signalling only that all finished. You read each original future's result yourself afterward (e.g. with join).

If any stage throws or its upstream failed, that stage completes exceptionally and every following thenApply/thenCompose is skipped — the error 'short-circuits' to the end. You handle it with exceptionally, handle, or whenComplete.

It's not the creating thread — it's the completing thread (whichever thread finishes the previous stage), or the caller if the stage was already done. The creating thread is usually irrelevant.

There are six two-input methods in a 3x2 grid: wait for BOTH (thenCombine, thenAcceptBoth, runAfterBoth) or EITHER first (applyToEither, acceptEither, runAfterEither). Within each row the callback is a function (returns a value), a consumer (side effect), or a runnable (ignores results).

The 'either' methods react to whichever of two futures finishes first. applyToEither passes that first result to a function; the 'both' methods instead wait for both futures to complete.

These methods peek at the future without waiting. isDone tells you if it's finished (any way). isCancelled and isCompletedExceptionally tell you how it finished. getNow(default) returns the value right now if ready, otherwise your default — it never blocks.

Create an empty future with new CompletableFuture<>(), then call complete(value) when the result arrives, or completeExceptionally(error) on failure. It's useful for bridging callback-based APIs into the CompletableFuture world.

Dependent stages still run in order — each waits for the previous result. But *Async does not guarantee the same thread for each stage, and sibling stages attached to the same future can run concurrently in any order.

Both (Java 9+) put a time limit on the future itself, not just on a waiting caller. orTimeout fails it with a TimeoutException if it's late; completeOnTimeout finishes it with a fallback value instead. Unlike get(timeout), they actually settle the future.

The exception is captured and the future completes exceptionally—it does not propagate out of supplyAsync. A later get() then throws an ExecutionException whose cause is the thrown exception; join() throws a CompletionException wrapping it.

Both run a task and return a Future, but ExecutorService.submit gives a plain Future you can only block on with get(). supplyAsync returns a CompletableFuture you can chain non-blocking steps onto (thenApply, thenCompose, combine) and add error recovery.

exceptionally returns a plain fallback value on error. exceptionallyCompose returns a whole new CompletableFuture on error — so the fallback can itself be asynchronous, like calling a backup service. It is the error-path version of thenCompose.

get() throws the checked ExecutionException (and you must catch it), while join() throws the unchecked CompletionException. Both wrap the real cause, so you call getCause() to reach it. join() is friendlier in lambdas.

No. thenApply and thenApplyAsync produce the same logical order — each stage still waits for the one before it. The 'Async' suffix only controls which thread the callback runs on, not whether stages run in parallel or reorder.

CompletableFuture.cancel() just completes the future with a CancellationException — it does not interrupt the thread running your task, and downstream-only cancellation doesn't travel back to upstream stages. To really stop work you need cooperative cancellation (check a flag / interrupt) and you must cancel the right (upstream) stages.

The Async variants run the callback on a separate thread pool instead of whatever thread completed the previous stage. Without an Executor they use the shared common ForkJoinPool; passing your own pool keeps blocking work off that shared pool.

Separate the work: keep cheap CPU transforms on non-async or the common pool, and give blocking I/O its own dedicated, bounded executor (or virtual threads). Use one pool per downstream so a slow dependency can't starve the rest.