CompletableFuture
open class CompletableFuture<T : Any!> : Future<T>, CompletionStage<T>
A Future that may be explicitly completed (setting its value and status), and may be used as a CompletionStage, supporting dependent functions 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, CompletableFuture implements interface CompletionStage with the following policies:
- Actions supplied for dependent completions of non-async methods may be performed by the thread that completes the current CompletableFuture, or by any other caller of a completion method.
- All async methods without an explicit Executor argument 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). To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interface AsynchronousCompletionTask. Operations with time-delays can use adapter methods defined in this class, for example: supplyAsync(supplier, delayedExecutor(timeout, timeUnit)). To support methods with delays and timeouts, this class maintains at most one daemon thread for triggering and cancelling actions, not for running them.
- 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.
CompletableFuture also implements Future with the following policies:
- Since (unlike
FutureTask) this class has no direct control over the computation that causes it to be completed, cancellation is treated as just another form of exceptional completion. Method cancel has the same effect as completeExceptionally(new CancellationException()). Method isCompletedExceptionally can be used to determine if a CompletableFuture completed in any exceptional fashion.
- In case of exceptional completion with a CompletionException, methods
get() and get(long,java.util.concurrent.TimeUnit) throw an ExecutionException with the same cause as held in the corresponding CompletionException. To simplify usage in most contexts, this class also defines methods join() and getNow that instead throw the CompletionException directly in these cases.
Arguments used to pass a completion result (that is, for parameters of type T) for methods accepting them may be null, but passing a null value for any other parameter will result in a NullPointerException being thrown.
Summary
| Nested classes |
| abstract |
A marker interface identifying asynchronous tasks produced by async methods.
|
| Public constructors |
|
Creates a new incomplete CompletableFuture.
|
| Public methods |
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open static CompletableFuture<Void!>! |
Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete.
|
| open static CompletableFuture<Any!>! |
Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result.
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open Boolean |
If not already completed, completes this CompletableFuture with a CancellationException.
|
| open Boolean |
If not already completed, sets the value returned by and related methods to the given value.
|
| open Boolean |
If not already completed, causes invocations of get() and related methods to throw the given exception.
|
| open static CompletableFuture<U>! |
Returns a new CompletableFuture that is already completed with the given value.
|
| open CompletableFuture<T>! |
Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value.
|
| open T |
Waits if necessary for this future to complete, and then returns its result.
|
| open T |
Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
|
| open T |
Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.
|
| open Int |
Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture.
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open Boolean |
Returns true if this CompletableFuture was cancelled before it completed normally.
|
| open Boolean |
Returns true if this CompletableFuture completed exceptionally, in any way.
|
| open Boolean |
Returns true if completed in any fashion: normally, exceptionally, or via cancellation.
|
| open T |
Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.
|
| open Unit |
Forcibly causes subsequent invocations of method get() and related methods to throw the given exception, whether or not already completed.
|
| open Unit |
Forcibly sets or resets the value subsequently returned by method get() and related methods, whether or not already completed.
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open static CompletableFuture<Void!>! |
Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool#commonPool() after it runs the given action.
|
| open static CompletableFuture<Void!>! |
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action.
|
| open static CompletableFuture<U>! |
Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool#commonPool() with the value obtained by calling the given Supplier.
|
| open static CompletableFuture<U>! |
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<V>! |
|
| open CompletableFuture<V>! |
|
| open CompletableFuture<V>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<U>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<Void!>! |
|
| open CompletableFuture<T>! |
Returns this CompletableFuture.
|
| open String |
Returns a string identifying this CompletableFuture, as well as its completion state.
|
| open CompletableFuture<T>! |
|
| open CompletableFuture<T>! |
|
| open CompletableFuture<T>! |
|
Public constructors
<init>
CompletableFuture()
Creates a new incomplete CompletableFuture.
Public methods
allOf
open static fun allOf(vararg cfs: CompletableFuture<*>!): CompletableFuture<Void!>!
Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. Otherwise, the results, if any, of the given CompletableFutures are not reflected in the returned CompletableFuture, but may be obtained by inspecting them individually. If no CompletableFutures are provided, returns a CompletableFuture completed with the value null.
Among the applications of this method is to await completion of a set of independent CompletableFutures before continuing a program, as in: CompletableFuture.allOf(c1, c2, c3).join();.
| Return |
CompletableFuture<Void!>! |
a new CompletableFuture that is completed when all of the given CompletableFutures complete |
| Exceptions |
java.lang.NullPointerException |
if the array or any of its elements are null |
anyOf
open static fun anyOf(vararg cfs: CompletableFuture<*>!): CompletableFuture<Any!>!
Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result. Otherwise, if it completed exceptionally, the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns an incomplete CompletableFuture.
| Return |
CompletableFuture<Any!>! |
a new CompletableFuture that is completed with the result or exception of any of the given CompletableFutures when one completes |
| Exceptions |
java.lang.NullPointerException |
if the array or any of its elements are null |
applyToEitherAsync
open fun <U : Any!> applyToEitherAsync(
other: CompletionStage<out T>!,
fn: Function<in T, U>!
): CompletableFuture<U>!
| Parameters |
other |
CompletionStage<out T>!: the other CompletionStage |
fn |
Function<in T, U>!: the function to use to compute the value of the returned CompletionStage |
<U> |
the function's return type |
applyToEitherAsync
open fun <U : Any!> applyToEitherAsync(
other: CompletionStage<out T>!,
fn: Function<in T, U>!,
executor: Executor!
): CompletableFuture<U>!
| Parameters |
other |
CompletionStage<out T>!: the other CompletionStage |
fn |
Function<in T, U>!: the function to use to compute the value of the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
<U> |
the function's return type |
cancel
open fun cancel(mayInterruptIfRunning: Boolean): Boolean
If not already completed, completes this CompletableFuture with a CancellationException. Dependent CompletableFutures that have not already completed will also complete exceptionally, with a CompletionException caused by this CancellationException.
| Parameters |
mayInterruptIfRunning |
Boolean: this value has no effect in this implementation because interrupts are not used to control processing. |
| Return |
Boolean |
true if this task is now cancelled |
complete
open fun complete(value: T): Boolean
If not already completed, sets the value returned by and related methods to the given value.
| Parameters |
value |
T: the result value |
| Return |
Boolean |
true if this invocation caused this CompletableFuture to transition to a completed state, else false |
completeExceptionally
open fun completeExceptionally(ex: Throwable!): Boolean
If not already completed, causes invocations of get() and related methods to throw the given exception.
| Return |
Boolean |
true if this invocation caused this CompletableFuture to transition to a completed state, else false |
completedFuture
open static fun <U : Any!> completedFuture(value: U): CompletableFuture<U>!
Returns a new CompletableFuture that is already completed with the given value.
| Parameters |
value |
U: the value |
<U> |
the type of the value |
exceptionally
open fun exceptionally(fn: Function<Throwable!, out T>!): CompletableFuture<T>!
Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value. Note: More flexible versions of this functionality are available using methods whenComplete and handle.
| Parameters |
fn |
Function<Throwable!, out T>!: the function to use to compute the value of the returned CompletableFuture if this CompletableFuture completed exceptionally |
get
open fun get(): T
Waits if necessary for this future to complete, and then returns its result.
| Return |
T |
the result value |
| Exceptions |
java.util.concurrent.CancellationException |
if this future was cancelled |
java.util.concurrent.ExecutionException |
if this future completed exceptionally |
java.lang.InterruptedException |
if the current thread was interrupted while waiting |
get
open fun get(
timeout: Long,
unit: TimeUnit!
): T
Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
| Parameters |
timeout |
Long: the maximum time to wait |
unit |
TimeUnit!: the time unit of the timeout argument |
| Return |
T |
the result value |
| Exceptions |
java.util.concurrent.CancellationException |
if this future was cancelled |
java.util.concurrent.ExecutionException |
if this future completed exceptionally |
java.lang.InterruptedException |
if the current thread was interrupted while waiting |
java.util.concurrent.TimeoutException |
if the wait timed out |
getNow
open fun getNow(valueIfAbsent: T): T
Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.
| Parameters |
valueIfAbsent |
T: the value to return if not completed |
| Return |
T |
the result value, if completed, else the given valueIfAbsent |
| Exceptions |
java.util.concurrent.CancellationException |
if the computation was cancelled |
java.util.concurrent.CompletionException |
if this future completed exceptionally or a completion computation threw an exception |
getNumberOfDependents
open fun getNumberOfDependents(): Int
Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture. This method is designed for use in monitoring system state, not for synchronization control.
| Return |
Int |
the number of dependent CompletableFutures |
isCancelled
open fun isCancelled(): Boolean
Returns true if this CompletableFuture was cancelled before it completed normally.
| Return |
Boolean |
true if this CompletableFuture was cancelled before it completed normally |
isCompletedExceptionally
open fun isCompletedExceptionally(): Boolean
Returns true if this CompletableFuture completed exceptionally, in any way. Possible causes include cancellation, explicit invocation of completeExceptionally, and abrupt termination of a CompletionStage action.
| Return |
Boolean |
true if this CompletableFuture completed exceptionally |
isDone
open fun isDone(): Boolean
Returns true if completed in any fashion: normally, exceptionally, or via cancellation.
join
open fun join(): T
Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally. To better conform with the use of common functional forms, if a computation involved in the completion of this CompletableFuture threw an exception, this method throws an (unchecked) CompletionException with the underlying exception as its cause.
| Return |
T |
the result value |
| Exceptions |
java.util.concurrent.CancellationException |
if the computation was cancelled |
java.util.concurrent.CompletionException |
if this future completed exceptionally or a completion computation threw an exception |
obtrudeException
open fun obtrudeException(ex: Throwable!): Unit
Forcibly causes subsequent invocations of method get() and related methods to throw the given exception, whether or not already completed. This method is designed for use only in error recovery actions, and even in such situations may result in ongoing dependent completions using established versus overwritten outcomes.
| Exceptions |
java.lang.NullPointerException |
if the exception is null |
obtrudeValue
open fun obtrudeValue(value: T): Unit
Forcibly sets or resets the value subsequently returned by method get() and related methods, whether or not already completed. This method is designed for use only in error recovery actions, and even in such situations may result in ongoing dependent completions using established versus overwritten outcomes.
| Parameters |
value |
T: the completion value |
runAsync
open static fun runAsync(runnable: Runnable!): CompletableFuture<Void!>!
Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool#commonPool() after it runs the given action.
| Parameters |
runnable |
Runnable!: the action to run before completing the returned CompletableFuture |
runAsync
open static fun runAsync(
runnable: Runnable!,
executor: Executor!
): CompletableFuture<Void!>!
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action.
| Parameters |
runnable |
Runnable!: the action to run before completing the returned CompletableFuture |
executor |
Executor!: the executor to use for asynchronous execution |
supplyAsync
open static fun <U : Any!> supplyAsync(supplier: Supplier<U>!): CompletableFuture<U>!
Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool#commonPool() with the value obtained by calling the given Supplier.
| Parameters |
supplier |
Supplier<U>!: a function returning the value to be used to complete the returned CompletableFuture |
<U> |
the function's return type |
supplyAsync
open static fun <U : Any!> supplyAsync(
supplier: Supplier<U>!,
executor: Executor!
): CompletableFuture<U>!
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.
| Parameters |
supplier |
Supplier<U>!: a function returning the value to be used to complete the returned CompletableFuture |
executor |
Executor!: the executor to use for asynchronous execution |
<U> |
the function's return type |
thenAccept
open fun thenAccept(action: Consumer<in T>!): CompletableFuture<Void!>!
| Parameters |
action |
Consumer<in T>!: the action to perform before completing the returned CompletionStage |
thenAcceptAsync
open fun thenAcceptAsync(action: Consumer<in T>!): CompletableFuture<Void!>!
| Parameters |
action |
Consumer<in T>!: the action to perform before completing the returned CompletionStage |
thenAcceptAsync
open fun thenAcceptAsync(
action: Consumer<in T>!,
executor: Executor!
): CompletableFuture<Void!>!
| Parameters |
action |
Consumer<in T>!: the action to perform before completing the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
thenAcceptBothAsync
open fun <U : Any!> thenAcceptBothAsync(
other: CompletionStage<out U>!,
action: BiConsumer<in T, in U>!
): CompletableFuture<Void!>!
| Parameters |
other |
CompletionStage<out U>!: the other CompletionStage |
action |
BiConsumer<in T, in U>!: the action to perform before completing the returned CompletionStage |
<U> |
the type of the other CompletionStage's result |
thenAcceptBothAsync
open fun <U : Any!> thenAcceptBothAsync(
other: CompletionStage<out U>!,
action: BiConsumer<in T, in U>!,
executor: Executor!
): CompletableFuture<Void!>!
| Parameters |
other |
CompletionStage<out U>!: the other CompletionStage |
action |
BiConsumer<in T, in U>!: the action to perform before completing the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
<U> |
the type of the other CompletionStage's result |
thenApply
open fun <U : Any!> thenApply(fn: Function<in T, out U>!): CompletableFuture<U>!
| Parameters |
fn |
Function<in T, out U>!: the function to use to compute the value of the returned CompletionStage |
<U> |
the function's return type |
thenApplyAsync
open fun <U : Any!> thenApplyAsync(fn: Function<in T, out U>!): CompletableFuture<U>!
| Parameters |
fn |
Function<in T, out U>!: the function to use to compute the value of the returned CompletionStage |
<U> |
the function's return type |
thenApplyAsync
open fun <U : Any!> thenApplyAsync(
fn: Function<in T, out U>!,
executor: Executor!
): CompletableFuture<U>!
| Parameters |
fn |
Function<in T, out U>!: the function to use to compute the value of the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
<U> |
the function's return type |
thenCombine
open fun <U : Any!, V : Any!> thenCombine(
other: CompletionStage<out U>!,
fn: BiFunction<in T, in U, out V>!
): CompletableFuture<V>!
| Parameters |
other |
CompletionStage<out U>!: the other CompletionStage |
fn |
BiFunction<in T, in U, out V>!: the function to use to compute the value of the returned CompletionStage |
<U> |
the type of the other CompletionStage's result |
<V> |
the function's return type |
thenCombineAsync
open fun <U : Any!, V : Any!> thenCombineAsync(
other: CompletionStage<out U>!,
fn: BiFunction<in T, in U, out V>!
): CompletableFuture<V>!
| Parameters |
other |
CompletionStage<out U>!: the other CompletionStage |
fn |
BiFunction<in T, in U, out V>!: the function to use to compute the value of the returned CompletionStage |
<U> |
the type of the other CompletionStage's result |
<V> |
the function's return type |
thenCombineAsync
open fun <U : Any!, V : Any!> thenCombineAsync(
other: CompletionStage<out U>!,
fn: BiFunction<in T, in U, out V>!,
executor: Executor!
): CompletableFuture<V>!
| Parameters |
other |
CompletionStage<out U>!: the other CompletionStage |
fn |
BiFunction<in T, in U, out V>!: the function to use to compute the value of the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
<U> |
the type of the other CompletionStage's result |
<V> |
the function's return type |
thenRunAsync
open fun thenRunAsync(
action: Runnable!,
executor: Executor!
): CompletableFuture<Void!>!
| Parameters |
action |
Runnable!: the action to perform before completing the returned CompletionStage |
executor |
Executor!: the executor to use for asynchronous execution |
toCompletableFuture
open fun toCompletableFuture(): CompletableFuture<T>!
Returns this CompletableFuture.
| Exceptions |
java.lang.UnsupportedOperationException |
if this implementation does not interoperate with CompletableFuture |
toString
open fun toString(): String
Returns a string identifying this CompletableFuture, as well as its completion state. The state, in brackets, contains the String "Completed Normally" or the String "Completed Exceptionally", or the String "Not completed" followed by the number of CompletableFutures dependent upon its completion, if any.
| Return |
String |
a string identifying this CompletableFuture, as well as its state |
