diff --git a/src/share/classes/java/util/concurrent/CompletableFuture.java b/src/share/classes/java/util/concurrent/CompletableFuture.java index 7926f2e63b93d434109f7b1a9c325b3e5588524f..5e2fb134fc1887c653ee34a884011d1f7a3a3d37 100644 --- a/src/share/classes/java/util/concurrent/CompletableFuture.java +++ b/src/share/classes/java/util/concurrent/CompletableFuture.java @@ -48,13 +48,16 @@ import java.util.concurrent.ThreadLocalRandom; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeoutException; import java.util.concurrent.CancellationException; +import java.util.concurrent.CompletionException; +import java.util.concurrent.CompletionStage; import java.util.concurrent.atomic.AtomicInteger; import java.util.concurrent.locks.LockSupport; /** * A {@link Future} that may be explicitly completed (setting its - * value and status), and may include dependent functions and actions - * that trigger upon its completion. + * value and status), and may be used as a {@link CompletionStage}, + * supporting dependent functions and actions that trigger upon its + * completion. * *
When two or more threads attempt to * {@link #complete complete}, @@ -62,64 +65,50 @@ import java.util.concurrent.locks.LockSupport; * {@link #cancel cancel} * a CompletableFuture, only one of them succeeds. * - *
Methods are available for adding dependents based on - * user-provided Functions, Consumers, or Runnables. The appropriate - * form to use depends on whether actions require arguments and/or - * produce results. Completion of a dependent action will trigger the - * completion of another CompletableFuture. Actions may also be - * triggered after either or both the current and another - * CompletableFuture complete. Multiple CompletableFutures may also - * be grouped as one using {@link #anyOf(CompletableFuture...)} and - * {@link #allOf(CompletableFuture...)}. + *
In addition to these and related methods for directly + * manipulating status and results, CompletableFuture implements + * interface {@link CompletionStage} with the following policies:
CompletableFutures themselves do not execute asynchronously. - * However, actions supplied for dependent completions of another - * CompletableFuture may do so, depending on whether they are provided - * via one of the async methods (that is, methods with names - * of the form xxxAsync). The async - * methods provide a way to commence asynchronous processing of an - * action using either a given {@link Executor} or by default the - * {@link ForkJoinPool#commonPool()}. To simplify monitoring, + *
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 these methods. There - * are no guarantees about the order of processing completions unless - * constrained by these methods. + *
Since (unlike {@link 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 {@link #cancel cancel} has the same effect as - * {@code completeExceptionally(new CancellationException())}. + *
CompletableFuture also implements {@link Future} with the following + * policies:
Upon exceptional completion (including cancellation), or when a - * completion entails an additional computation which terminates - * abruptly with an (unchecked) exception or error, then all of their - * dependent completions (and their dependents in turn) generally act - * as {@code completeExceptionally} with a {@link CompletionException} - * holding that exception as its cause. However, the {@link - * #exceptionally exceptionally} and {@link #handle handle} - * completions are able to handle exceptional completions of - * the CompletableFutures they depend on. + *
In case of exceptional completion with a CompletionException, + *
Arguments used to pass a completion result (that is, for parameters - * of type {@code T}) may be null, but passing a null value for any other - * parameter will result in a {@link NullPointerException} being thrown. + * corresponding CompletionException. To simplify usage in most + * contexts, this class also defines methods {@link #join()} and + * {@link #getNow} that instead throw the CompletionException directly + * in these cases.
If this CompletableFuture completes exceptionally, or the - * supplied function throws an exception, then the returned - * CompletableFuture completes exceptionally with a - * CompletionException holding the exception as its cause. - * - * @param fn the function to use to compute the value of - * the returned CompletableFuture - * @return the new CompletableFuture - */ - public CompletableFuture thenApply(Function super T,? extends U> fn) { - return doThenApply(fn, null); - } - - /** - * Returns a new CompletableFuture that is asynchronously completed - * when this CompletableFuture completes, with the result of the - * given function of this CompletableFuture's result from a - * task running in the {@link ForkJoinPool#commonPool()}. - * - *
If this CompletableFuture completes exceptionally, or the - * supplied function throws an exception, then the returned - * CompletableFuture completes exceptionally with a - * CompletionException holding the exception as its cause. - * - * @param fn the function to use to compute the value of - * the returned CompletableFuture - * @return the new CompletableFuture - */ - public CompletableFuture thenApplyAsync - (Function super T,? extends U> fn) { - return doThenApply(fn, ForkJoinPool.commonPool()); - } - - /** - * Returns a new CompletableFuture that is asynchronously completed - * when this CompletableFuture completes, with the result of the - * given function of this CompletableFuture's result from a - * task running in the given executor. - * - *
If this CompletableFuture completes exceptionally, or the
- * supplied function throws an exception, then the returned
- * CompletableFuture completes exceptionally with a
- * CompletionException holding the exception as its cause.
- *
- * @param fn the function to use to compute the value of
- * the returned CompletableFuture
- * @param executor the executor to use for asynchronous execution
- * @return the new CompletableFuture
- */
- public CompletableFuture thenApplyAsync
- (Function super T,? extends U> fn,
- Executor executor) {
- if (executor == null) throw new NullPointerException();
- return doThenApply(fn, executor);
- }
-
- private CompletableFuture doThenApply
- (Function super T,? extends U> fn,
- Executor e) {
- if (fn == null) throw new NullPointerException();
- CompletableFuture dst = new CompletableFuture();
- ThenApply If this CompletableFuture completes exceptionally, or the
- * supplied action throws an exception, then the returned
- * CompletableFuture completes exceptionally with a
- * CompletionException holding the exception as its cause.
+ * If not already completed, sets the value returned by {@link
+ * #get()} and related methods to the given value.
*
- * @param block the action to perform before completing the
- * returned CompletableFuture
- * @return the new CompletableFuture
+ * @param value the result value
+ * @return {@code true} if this invocation caused this CompletableFuture
+ * to transition to a completed state, else {@code false}
*/
- public CompletableFuture If this CompletableFuture completes exceptionally, or the
- * supplied action throws an exception, then the returned
- * CompletableFuture completes exceptionally with a
- * CompletionException holding the exception as its cause.
+ * If not already completed, causes invocations of {@link #get()}
+ * and related methods to throw the given exception.
*
- * @param block the action to perform before completing the
- * returned CompletableFuture
- * @return the new CompletableFuture
+ * @param ex the exception
+ * @return {@code true} if this invocation caused this CompletableFuture
+ * to transition to a completed state, else {@code false}
*/
- public CompletableFuture If this CompletableFuture completes exceptionally, or the
- * supplied action throws an exception, then the returned
- * CompletableFuture completes exceptionally with a
- * CompletionException holding the exception as its cause.
- *
- * @param block the action to perform before completing the
- * returned CompletableFuture
- * @param executor the executor to use for asynchronous execution
- * @return the new CompletableFuture
- */
- public CompletableFuture