CompletableFuture

java.util.concurrent Interface CompletionStage

A stage of a possibly asynchronous computation, possibly because it might be there or might not be.

The computation performed by a stage may be expressed as a Function, Consumer, or Runnable (using methods with names including apply(for function), accept(for Consumer), or run(for custom Runnable), respectively) depending on whether it requires arguments(this is the case for function) and/or produces results(this is for Function/Consumer).

For example,

Stage.thenApply(x -> square(x)).

thenAccept(x -> System.out.print(x)).

thenRun(() ->System.out.println())

An additional form (compose) applies functions of stages themselves, rather than their results. using thenCompose

The computation performs an action(in case it's a consumer with no return value) or computes a value(in case it's a function) when another CompletionStage completes(chaining of completionStages). A stage completes upon termination of its computation, but this may in turn trigger other dependent stages. The functionality defined in this interface takes only a few basic forms, which expand out to a larger set of methods to capture a range of usage styles:

One stage's execution may be trigger by completion of a single stage, or both of two stages, or either of two stages.

the stages may be triggered by chaining using prefix "then" like thenApply, thenAccept, thenRun. Those triggered by completion of both of two stages may combine their results or effects, using correspondingly named methods such as thenAcceptBoth, thenAcceptBothAsync. Those triggered by either of two stages make no guarantees about which of the results or effects are used for the dependent stage's computation the methods available are acceptEither/applyEither/runAfterEIther

Dependencies among stages control the triggering of computations, but do not otherwise guarantee any particular ordering. Additionally, execution of a new stage's computations may be arranged in any of three ways: default execution(the then methods), default asynchronous execution(thenAsync) (using methods with suffix async that employ the stage's default asynchronous execution facility), or custom (via a supplied Executor). Methods with explicit Executor arguments may have arbitrary execution properties, and might not even support concurrent execution, but are arranged for processing in a way that accommodates asynchrony.

public class CompletableFuture

extends Object

implements Future, CompletionStage

A Future that may be explicitly completed (setting its value and status), and may be used as a CompletionStage(because it inherits from the interface), supporting dependent functions(apply,accept,run) and actions that trigger upon its completion. When two or more threads attempt to complete, completeExceptionally, or cancel a CompletableFuture, only one of them succeeds.

In addition to these and related methods for directly manipulating status and results(apply,accept,run), CompletableFuture implements interface CompletionStage with the following policies:

All async methods without an explicit Executor argument suchAs

acceptEitherAsync(CompletionStage other, Consumer action)

vs

CompletionStage<> acceptEitherAsync(CompletionStage other, Consumer action, Executor executor)

are performed using the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least two, in which case, a new Thread is created to run each task).

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function.

To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interface CompletableFuture.AsynchronousCompletionTask.

All CompletionStage methods are implemented independently of other public methods, so the behavior of one method is not impacted by overrides of others in subclasses.