jdk.util.concurrent.CompletionStage

Liking cljdoc? Tell your friends :D

Clojure only.

A stage of a possibly asynchronous computation, that performs an action or computes a value when another CompletionStage completes. 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:

The computation performed by a stage may be expressed as a Function, Consumer, or Runnable (using methods with names including apply, accept, or run, respectively) depending on whether it requires arguments and/or produces results. 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.

One stage's execution may be triggered by completion of a single stage, or both of two stages, or either of two stages. Dependencies on a single stage are arranged using methods with prefix then. Those triggered by completion of both of two stages may combine their results or effects, using correspondingly named methods. 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.

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, default asynchronous execution (using methods with suffix async that employ the stage's default asynchronous execution facility), or custom (via a supplied Executor). The execution properties of default and async modes are specified by CompletionStage implementations, not this interface. 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.

Two method forms support processing whether the triggering stage completed normally or exceptionally: Method whenComplete allows injection of an action regardless of outcome, otherwise preserving the outcome in its completion. Method handle additionally allows the stage to compute a replacement result that may enable further processing by other dependent stages. In all other cases, if a stage's computation terminates abruptly with an (unchecked) exception or error, then all dependent stages requiring its completion complete exceptionally as well, with a CompletionException holding the exception as its cause. If a stage is dependent on both of two stages, and both complete exceptionally, then the CompletionException may correspond to either one of these exceptions. If a stage is dependent on either of two others, and only one of them completes exceptionally, no guarantees are made about whether the dependent stage completes normally or exceptionally. In the case of method whenComplete, when the supplied action itself encounters an exception, then the stage exceptionally completes with this exception if not already completed exceptionally.

All methods adhere to the above triggering, execution, and exceptional completion specifications (which are not repeated in individual method specifications). Additionally, while arguments used to pass a completion result (that is, for parameters of type T) for methods accepting them may be null, passing a null value for any other parameter will result in a NullPointerException being thrown.

This interface does not define methods for initially creating, forcibly completing normally or exceptionally, probing completion status or results, or awaiting completion of a stage. Implementations of CompletionStage may provide means of achieving such effects, as appropriate. Method toCompletableFuture() enables interoperability among different implementations of this interface by providing a common conversion type.

A stage of a possibly asynchronous computation, that performs an
action or computes a value when another CompletionStage completes.
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:

The computation performed by a stage may be expressed as a
Function, Consumer, or Runnable (using methods with names including
apply, accept, or run, respectively)
depending on whether it requires arguments and/or produces results.
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.

One stage's execution may be triggered by completion of a
single stage, or both of two stages, or either of two stages.
Dependencies on a single stage are arranged using methods with
prefix then. Those triggered by completion of
both of two stages may combine their results or
effects, using correspondingly named methods. 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.

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, default
asynchronous execution (using methods with suffix async
that employ the stage's default asynchronous execution facility),
or custom (via a supplied Executor). The execution
properties of default and async modes are specified by
CompletionStage implementations, not this interface. 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.

Two method forms support processing whether the triggering
stage completed normally or exceptionally: Method whenComplete allows injection of an action
regardless of outcome, otherwise preserving the outcome in its
completion. Method handle additionally allows the
stage to compute a replacement result that may enable further
processing by other dependent stages. In all other cases, if a
stage's computation terminates abruptly with an (unchecked)
exception or error, then all dependent stages requiring its
completion complete exceptionally as well, with a CompletionException holding the exception as its cause. If a
stage is dependent on both of two stages, and both
complete exceptionally, then the CompletionException may correspond
to either one of these exceptions. If a stage is dependent on
either of two others, and only one of them completes
exceptionally, no guarantees are made about whether the dependent
stage completes normally or exceptionally. In the case of method
whenComplete, when the supplied action itself encounters an
exception, then the stage exceptionally completes with this
exception if not already completed exceptionally.

All methods adhere to the above triggering, execution, and
exceptional completion specifications (which are not repeated in
individual method specifications). Additionally, while arguments
used to pass a completion result (that is, for parameters of type
T) for methods accepting them may be null, passing a null
value for any other parameter will result in a NullPointerException being thrown.

This interface does not define methods for initially creating,
forcibly completing normally or exceptionally, probing completion
status or results, or awaiting completion of a stage.
Implementations of CompletionStage may provide means of achieving
such effects, as appropriate. Method toCompletableFuture()
enables interoperability among different implementations of this
interface by providing a common conversion type.

jdk.util.concurrent.CompletionStage

accept-eitherclj

accept-either-asyncclj

apply-to-eitherclj

apply-to-either-asyncclj

exceptionallyclj

handleclj

handle-asyncclj

run-after-bothclj

run-after-both-asyncclj

run-after-eitherclj

run-after-either-asyncclj

then-acceptclj

then-accept-asyncclj

then-accept-bothclj

then-accept-both-asyncclj

then-applyclj

then-apply-asyncclj

then-combineclj

then-combine-asyncclj

then-composeclj

then-compose-asyncclj

then-runclj

then-run-asyncclj

to-completable-futureclj

when-completeclj

when-complete-asyncclj

accept-either^clj

accept-either-async^clj

apply-to-either^clj

apply-to-either-async^clj

exceptionally^clj

handle^clj

handle-async^clj

run-after-both^clj

run-after-both-async^clj

run-after-either^clj

run-after-either-async^clj

then-accept^clj

then-accept-async^clj

then-accept-both^clj

then-accept-both-async^clj

then-apply^clj

then-apply-async^clj

then-combine^clj

then-combine-async^clj

then-compose^clj

then-compose-async^clj

then-run^clj

then-run-async^clj

to-completable-future^clj

when-complete^clj

when-complete-async^clj