CompletionStage

CompletionStage is a Java interface in the java.util.concurrent package that represents a stage of an asynchronous computation. A CompletionStage models the future result of a computation, which may complete normally with a value or exceptionally with an error. It does not itself hold a result; instead it provides a pipeline of dependent stages that will execute when the preceding stage completes.

Most commonly, CompletionStage is implemented by CompletableFuture, which provides the actual asynchronous execution and also implements Future. The methods defined by CompletionStage, such as thenApply, thenAccept, thenRun, thenCompose, and thenCombine, allow chaining of actions and transformations. The stage's results can be transformed, consumed, or combined with other stages without blocking. There are also error-handling methods like exceptionally, handle, and whenComplete to respond to exceptional completion.

Execution semantics depend on the underlying executor; many chaining methods execute their actions asynchronously if the upstream stage completes asynchronously. Some methods accept functions and suppliers to produce new results, enabling complex pipelines of asynchronous tasks.

Converting to a concrete future is done via toCompletableFuture, enabling standard Future-based waiting or composition. CompletionStage emphasizes non-blocking, functional-style composition of asynchronous tasks, encouraging declarative pipelines over explicit callbacks.

See also: CompletableFuture, Future, asynchronous programming in Java.