diff --git a/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java b/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java index 0d26607591d60..c249f63016309 100644 --- a/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java +++ b/src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java @@ -44,16 +44,16 @@ import java.util.Objects; /** - * Provides default implementations of {@link ExecutorService} - * execution methods. This class implements the {@code submit}, - * {@code invokeAny} and {@code invokeAll} methods using a - * {@link RunnableFuture} returned by {@code newTaskFor}, which defaults - * to the {@link FutureTask} class provided in this package. For example, - * the implementation of {@code submit(Runnable)} creates an - * associated {@code RunnableFuture} that is executed and - * returned. Subclasses may override the {@code newTaskFor} methods - * to return {@code RunnableFuture} implementations other than - * {@code FutureTask}. + * Provides default implementations of {@link ExecutorService} methods + * other than {@link Executor#execute}. This class implements the {@code + * submit}, {@code invokeAny} and {@code invokeAll} methods using a + * {@link RunnableFuture} returned by {@code newTaskFor}, which + * defaults to the {@link FutureTask} class provided in this package. + * For example, the implementation of {@code submit(Runnable)} creates + * an associated {@code RunnableFuture} that is executed and + * returned. Subclasses may override the {@code newTaskFor} methods to + * return {@code RunnableFuture} implementations other than {@code + * FutureTask}. * *

Extension example. Here is a sketch of a class * that customizes {@link ThreadPoolExecutor} to use diff --git a/src/java.base/share/classes/java/util/concurrent/CompletionStage.java b/src/java.base/share/classes/java/util/concurrent/CompletionStage.java index 6ff31c61049cf..b43688428659e 100644 --- a/src/java.base/share/classes/java/util/concurrent/CompletionStage.java +++ b/src/java.base/share/classes/java/util/concurrent/CompletionStage.java @@ -43,7 +43,7 @@ /** * 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 + * A stage completes upon termination of its computation, which 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: @@ -97,18 +97,25 @@ * 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 - * {@link 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 - * {@code whenComplete}, when the supplied action itself encounters an - * exception, then the stage completes exceptionally with this - * exception unless the source stage also completed exceptionally, in - * which case the exceptional completion from the source stage is - * given preference and propagated to the dependent stage. + * {@link CompletionException} holding the exception as its + * cause. This convention distinguishes exceptions in an action itself + * from those it depends on. If they are to be handled in the same + * way, instead catch {@link RuntimeException} (possibly inspecting + * the exception's {@code getCause()}). 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 {@code whenComplete}, when the + * supplied action itself encounters an exception, then the stage + * completes exceptionally with that exception unless the source stage + * also completed exceptionally, in which case the exceptional + * completion from the source stage is given preference and propagated + * to the dependent stage. Applications are encouraged to maintain + * these conventions, avoiding unnecessary nesting when rethrowing, as + * in {@code throw (ex instanceof CompletionException) ? ex : new + * CompletionException(ex)}. * * * @@ -137,7 +144,7 @@ * } * }} * - *

This interface does not define methods for initially creating, + *

The {@code CompletionStage} 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 @@ -145,6 +152,13 @@ * enables interoperability among different implementations of this * interface by providing a common conversion type. * + *

Memory consistency effects: Actions in a thread prior to the + * submission of a computation producing a {@code CompletionStage} happen-before + * that computation begins. And actions taken by {@code + * CompletionStage x} happen-before actions of any dependent + * stage subsequent to {@code x}'s completion. + * * @param the type of values the stage produces or consumes * * @author Doug Lea @@ -153,8 +167,8 @@ public interface CompletionStage { /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed with this stage's result as the argument + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed with {@code this} stage's result as the argument * to the supplied function. * *

This method is analogous to @@ -172,9 +186,9 @@ public interface CompletionStage { public CompletionStage thenApply(Function fn); /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed using this stage's default asynchronous - * execution facility, with this stage's result as the argument to + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed using {@code this} stage's default asynchronous + * execution facility, with {@code this} stage's result as the argument to * the supplied function. * * See the {@link CompletionStage} documentation for rules @@ -189,8 +203,8 @@ public interface CompletionStage { (Function fn); /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed using the supplied Executor, with this + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed using the supplied Executor, with {@code this} * stage's result as the argument to the supplied function. * * See the {@link CompletionStage} documentation for rules @@ -207,8 +221,8 @@ public interface CompletionStage { Executor executor); /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed with this stage's result as the argument + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed with {@code this} stage's result as the argument * to the supplied action. * * See the {@link CompletionStage} documentation for rules @@ -221,9 +235,9 @@ public interface CompletionStage { public CompletionStage thenAccept(Consumer action); /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed using this stage's default asynchronous - * execution facility, with this stage's result as the argument to + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed using {@code this} stage's default asynchronous + * execution facility, with {@code this} stage's result as the argument to * the supplied action. * * See the {@link CompletionStage} documentation for rules @@ -236,8 +250,8 @@ public interface CompletionStage { public CompletionStage thenAcceptAsync(Consumer action); /** - * Returns a new CompletionStage that, when this stage completes - * normally, is executed using the supplied Executor, with this + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, is executed using the supplied Executor, with {@code this} * stage's result as the argument to the supplied action. * * See the {@link CompletionStage} documentation for rules @@ -251,7 +265,7 @@ public interface CompletionStage { public CompletionStage thenAcceptAsync(Consumer action, Executor executor); /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * normally, executes the given action. * * See the {@link CompletionStage} documentation for rules @@ -264,8 +278,8 @@ public CompletionStage thenAcceptAsync(Consumer action, public CompletionStage thenRun(Runnable action); /** - * Returns a new CompletionStage that, when this stage completes - * normally, executes the given action using this stage's default + * Returns a new CompletionStage that, when {@code this} stage completes + * normally, executes the given action using {@code this} stage's default * asynchronous execution facility. * * See the {@link CompletionStage} documentation for rules @@ -278,7 +292,7 @@ public CompletionStage thenAcceptAsync(Consumer action, public CompletionStage thenRunAsync(Runnable action); /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * normally, executes the given action using the supplied Executor. * * See the {@link CompletionStage} documentation for rules @@ -293,7 +307,7 @@ public CompletionStage thenRunAsync(Runnable action, Executor executor); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, is executed with the two * results as arguments to the supplied function. * @@ -312,8 +326,8 @@ public CompletionStage thenRunAsync(Runnable action, BiFunction fn); /** - * Returns a new CompletionStage that, when this and the other - * given stage both complete normally, is executed using this + * Returns a new CompletionStage that, when {@code this} and the other + * given stage both complete normally, is executed using {@code this} * stage's default asynchronous execution facility, with the two * results as arguments to the supplied function. * @@ -332,7 +346,7 @@ public CompletionStage thenRunAsync(Runnable action, BiFunction fn); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, is executed using the * supplied executor, with the two results as arguments to the * supplied function. @@ -354,7 +368,7 @@ public CompletionStage thenRunAsync(Runnable action, Executor executor); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, is executed with the two * results as arguments to the supplied action. * @@ -372,8 +386,8 @@ public CompletionStage thenRunAsync(Runnable action, BiConsumer action); /** - * Returns a new CompletionStage that, when this and the other - * given stage both complete normally, is executed using this + * Returns a new CompletionStage that, when {@code this} and the other + * given stage both complete normally, is executed using {@code this} * stage's default asynchronous execution facility, with the two * results as arguments to the supplied action. * @@ -391,7 +405,7 @@ public CompletionStage thenRunAsync(Runnable action, BiConsumer action); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, is executed using the * supplied executor, with the two results as arguments to the * supplied action. @@ -412,7 +426,7 @@ public CompletionStage thenRunAsync(Runnable action, Executor executor); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, executes the given action. * * See the {@link CompletionStage} documentation for rules @@ -426,9 +440,9 @@ public CompletionStage thenRunAsync(Runnable action, public CompletionStage runAfterBoth(CompletionStage other, Runnable action); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, executes the given action - * using this stage's default asynchronous execution facility. + * using {@code this} stage's default asynchronous execution facility. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. @@ -442,7 +456,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Runnable action); /** - * Returns a new CompletionStage that, when this and the other + * Returns a new CompletionStage that, when {@code this} and the other * given stage both complete normally, executes the given action * using the supplied executor. * @@ -459,7 +473,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Runnable action, Executor executor); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, is executed with the * corresponding result as argument to the supplied function. * @@ -477,8 +491,8 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Function fn); /** - * Returns a new CompletionStage that, when either this or the - * other given stage complete normally, is executed using this + * Returns a new CompletionStage that, when either {@code this} or the + * other given stage complete normally, is executed using {@code this} * stage's default asynchronous execution facility, with the * corresponding result as argument to the supplied function. * @@ -496,7 +510,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Function fn); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, is executed using the * supplied executor, with the corresponding result as argument to * the supplied function. @@ -517,7 +531,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Executor executor); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, is executed with the * corresponding result as argument to the supplied action. * @@ -534,8 +548,8 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Consumer action); /** - * Returns a new CompletionStage that, when either this or the - * other given stage complete normally, is executed using this + * Returns a new CompletionStage that, when either {@code this} or the + * other given stage complete normally, is executed using {@code this} * stage's default asynchronous execution facility, with the * corresponding result as argument to the supplied action. * @@ -552,7 +566,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Consumer action); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, is executed using the * supplied executor, with the corresponding result as argument to * the supplied action. @@ -572,7 +586,7 @@ public CompletionStage runAfterBothAsync(CompletionStage other, Executor executor); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, executes the given action. * * See the {@link CompletionStage} documentation for rules @@ -587,9 +601,9 @@ public CompletionStage runAfterEither(CompletionStage other, Runnable action); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, executes the given action - * using this stage's default asynchronous execution facility. + * using {@code this} stage's default asynchronous execution facility. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. @@ -604,7 +618,7 @@ public CompletionStage runAfterEither(CompletionStage other, Runnable action); /** - * Returns a new CompletionStage that, when either this or the + * Returns a new CompletionStage that, when either {@code this} or the * other given stage complete normally, executes the given action * using the supplied executor. * @@ -626,10 +640,10 @@ public CompletionStage runAfterEither(CompletionStage other, * Returns a new CompletionStage that is completed with the same * value as the CompletionStage returned by the given function. * - *

When this stage completes normally, the given function is - * invoked with this stage's result as the argument, returning + *

When {@code this} stage completes normally, the given function is + * invoked with {@code this} stage's result as the argument, returning * another CompletionStage. When that stage completes normally, - * the CompletionStage returned by this method is completed with + * the CompletionStage returned is completed with * the same value. * *

To ensure progress, the supplied function must arrange @@ -652,13 +666,13 @@ public CompletionStage runAfterEither(CompletionStage other, /** * Returns a new CompletionStage that is completed with the same * value as the CompletionStage returned by the given function, - * executed using this stage's default asynchronous execution + * executed using {@code this} stage's default asynchronous execution * facility. * - *

When this stage completes normally, the given function is - * invoked with this stage's result as the argument, returning + *

When {@code this} stage completes normally, the given function is + * invoked with {@code this} stage's result as the argument, returning * another CompletionStage. When that stage completes normally, - * the CompletionStage returned by this method is completed with + * the CompletionStage returned is completed with * the same value. * *

To ensure progress, the supplied function must arrange @@ -679,10 +693,10 @@ public CompletionStage runAfterEither(CompletionStage other, * value as the CompletionStage returned by the given function, * executed using the supplied Executor. * - *

When this stage completes normally, the given function is - * invoked with this stage's result as the argument, returning + *

When {@code this} stage completes normally, the given function is + * invoked with {@code this} stage's result as the argument, returning * another CompletionStage. When that stage completes normally, - * the CompletionStage returned by this method is completed with + * the CompletionStage returned by {@code this} method is completed with * the same value. * *

To ensure progress, the supplied function must arrange @@ -701,13 +715,13 @@ public CompletionStage runAfterEither(CompletionStage other, Executor executor); /** - * Returns a new CompletionStage that, when this stage completes - * either normally or exceptionally, is executed with this stage's + * Returns a new CompletionStage that, when {@code this} stage completes + * either normally or exceptionally, is executed with {@code this} stage's * result and exception as arguments to the supplied function. * - *

When this stage is complete, the given function is invoked + *

When {@code this} stage is complete, the given function is invoked * with the result (or {@code null} if none) and the exception (or - * {@code null} if none) of this stage as arguments, and the + * {@code null} if none) of {@code this} stage as arguments, and the * function's result is used to complete the returned stage. * * @param fn the function to use to compute the value of the @@ -719,14 +733,14 @@ public CompletionStage runAfterEither(CompletionStage other, (BiFunction fn); /** - * Returns a new CompletionStage that, when this stage completes - * either normally or exceptionally, is executed using this stage's - * default asynchronous execution facility, with this stage's + * Returns a new CompletionStage that, when {@code this} stage completes + * either normally or exceptionally, is executed using {@code this} stage's + * default asynchronous execution facility, with {@code this} stage's * result and exception as arguments to the supplied function. * - *

When this stage is complete, the given function is invoked + *

When {@code this} stage is complete, the given function is invoked * with the result (or {@code null} if none) and the exception (or - * {@code null} if none) of this stage as arguments, and the + * {@code null} if none) of {@code this} stage as arguments, and the * function's result is used to complete the returned stage. * * @param fn the function to use to compute the value of the @@ -738,14 +752,14 @@ public CompletionStage runAfterEither(CompletionStage other, (BiFunction fn); /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * either normally or exceptionally, is executed using the - * supplied executor, with this stage's result and exception as + * supplied executor, with {@code this} stage's result and exception as * arguments to the supplied function. * - *

When this stage is complete, the given function is invoked + *

When {@code this} stage is complete, the given function is invoked * with the result (or {@code null} if none) and the exception (or - * {@code null} if none) of this stage as arguments, and the + * {@code null} if none) of {@code this} stage as arguments, and the * function's result is used to complete the returned stage. * * @param fn the function to use to compute the value of the @@ -760,22 +774,22 @@ public CompletionStage runAfterEither(CompletionStage other, /** * Returns a new CompletionStage with the same result or exception as - * this stage, that executes the given action when this stage completes. + * {@code this} stage, that executes the given action when {@code this} stage completes. * - *

When this stage is complete, the given action is invoked + *

When {@code this} stage is complete, the given action is invoked * with the result (or {@code null} if none) and the exception (or - * {@code null} if none) of this stage as arguments. The returned + * {@code null} if none) of {@code this} stage as arguments. The returned * stage is completed when the action returns. * *

Unlike method {@link #handle handle}, - * this method is not designed to translate completion outcomes, + * method {@code whenComplete} is not designed to translate completion outcomes, * so the supplied action should not throw an exception. However, - * if it does, the following rules apply: if this stage completed + * if it does, the following rules apply: if {@code this} stage completed * normally but the supplied action throws an exception, then the * returned stage completes exceptionally with the supplied - * action's exception. Or, if this stage completed exceptionally + * action's exception. Or, if {@code this} stage completed exceptionally * and the supplied action throws an exception, then the returned - * stage completes exceptionally with this stage's exception. + * stage completes exceptionally with {@code this} stage's exception. * * @param action the action to perform * @return the new CompletionStage @@ -785,23 +799,23 @@ public CompletionStage runAfterEither(CompletionStage other, /** * Returns a new CompletionStage with the same result or exception as - * this stage, that executes the given action using this stage's - * default asynchronous execution facility when this stage completes. + * {@code this} stage, that executes the given action using {@code this} stage's + * default asynchronous execution facility when {@code this} stage completes. * - *

When this stage is complete, the given action is invoked with the + *

When {@code this} stage is complete, the given action is invoked with the * result (or {@code null} if none) and the exception (or {@code null} - * if none) of this stage as arguments. The returned stage is completed + * if none) of {@code this} stage as arguments. The returned stage is completed * when the action returns. * *

Unlike method {@link #handleAsync(BiFunction) handleAsync}, - * this method is not designed to translate completion outcomes, + * method {@code whenCompleteAsync} is not designed to translate completion outcomes, * so the supplied action should not throw an exception. However, - * if it does, the following rules apply: If this stage completed + * if it does, the following rules apply: If {@code this} stage completed * normally but the supplied action throws an exception, then the * returned stage completes exceptionally with the supplied - * action's exception. Or, if this stage completed exceptionally + * action's exception. Or, if {@code this} stage completed exceptionally * and the supplied action throws an exception, then the returned - * stage completes exceptionally with this stage's exception. + * stage completes exceptionally with {@code this} stage's exception. * * @param action the action to perform * @return the new CompletionStage @@ -811,23 +825,23 @@ public CompletionStage runAfterEither(CompletionStage other, /** * Returns a new CompletionStage with the same result or exception as - * this stage, that executes the given action using the supplied - * Executor when this stage completes. + * {@code this} stage, that executes the given action using the supplied + * Executor when {@code this} stage completes. * - *

When this stage is complete, the given action is invoked with the + *

When {@code this} stage is complete, the given action is invoked with the * result (or {@code null} if none) and the exception (or {@code null} - * if none) of this stage as arguments. The returned stage is completed + * if none) of {@code this} stage as arguments. The returned stage is completed * when the action returns. * *

Unlike method {@link #handleAsync(BiFunction,Executor) handleAsync}, - * this method is not designed to translate completion outcomes, + * method {@code whenCompleteAsync} is not designed to translate completion outcomes, * so the supplied action should not throw an exception. However, - * if it does, the following rules apply: If this stage completed + * if it does, the following rules apply: If {@code this} stage completed * normally but the supplied action throws an exception, then the * returned stage completes exceptionally with the supplied - * action's exception. Or, if this stage completed exceptionally + * action's exception. Or, if {@code this} stage completed exceptionally * and the supplied action throws an exception, then the returned - * stage completes exceptionally with this stage's exception. + * stage completes exceptionally with {@code this} stage's exception. * * @param action the action to perform * @param executor the executor to use for asynchronous execution @@ -838,14 +852,14 @@ public CompletionStage runAfterEither(CompletionStage other, Executor executor); /** - * Returns a new CompletionStage that, when this stage completes - * exceptionally, is executed with this stage's exception as the - * argument to the supplied function. Otherwise, if this stage + * Returns a new CompletionStage that, when {@code this} stage completes + * exceptionally, is executed with {@code this} stage's exception as the + * argument to the supplied function. Otherwise, if {@code this} stage * completes normally, then the returned stage also completes * normally with the same value. * * @param fn the function to use to compute the value of the - * returned CompletionStage if this CompletionStage completed + * returned CompletionStage if {@code this} CompletionStage completed * exceptionally * @return the new CompletionStage */ @@ -853,10 +867,10 @@ public CompletionStage runAfterEither(CompletionStage other, (Function fn); /** - * Returns a new CompletionStage that, when this stage completes - * exceptionally, is executed with this stage's exception as the - * argument to the supplied function, using this stage's default - * asynchronous execution facility. Otherwise, if this stage + * Returns a new CompletionStage that, when {@code this} stage completes + * exceptionally, is executed with {@code this} stage's exception as the + * argument to the supplied function, using {@code this} stage's default + * asynchronous execution facility. Otherwise, if {@code this} stage * completes normally, then the returned stage also completes * normally with the same value. * @@ -865,7 +879,7 @@ public CompletionStage runAfterEither(CompletionStage other, * #thenCompose} for result. * * @param fn the function to use to compute the value of the - * returned CompletionStage if this CompletionStage completed + * returned CompletionStage if {@code this} CompletionStage completed * exceptionally * @return the new CompletionStage * @since 12 @@ -879,10 +893,10 @@ public CompletionStage runAfterEither(CompletionStage other, } /** - * Returns a new CompletionStage that, when this stage completes - * exceptionally, is executed with this stage's exception as the + * Returns a new CompletionStage that, when {@code this} stage completes + * exceptionally, is executed with {@code this} stage's exception as the * argument to the supplied function, using the supplied Executor. - * Otherwise, if this stage completes normally, then the returned + * Otherwise, if {@code this} stage completes normally, then the returned * stage also completes normally with the same value. * * @implSpec The default implementation invokes {@link #handle}, @@ -890,7 +904,7 @@ public CompletionStage runAfterEither(CompletionStage other, * #thenCompose} for result. * * @param fn the function to use to compute the value of the - * returned CompletionStage if this CompletionStage completed + * returned CompletionStage if {@code this} CompletionStage completed * exceptionally * @param executor the executor to use for asynchronous execution * @return the new CompletionStage @@ -905,16 +919,16 @@ public CompletionStage runAfterEither(CompletionStage other, } /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * exceptionally, is composed using the results of the supplied - * function applied to this stage's exception. + * function applied to {@code this} stage's exception. * * @implSpec The default implementation invokes {@link #handle}, * invoking the given function on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the returned - * CompletionStage if this CompletionStage completed exceptionally + * CompletionStage if {@code this} CompletionStage completed exceptionally * @return the new CompletionStage * @since 12 */ @@ -927,9 +941,9 @@ public CompletionStage runAfterEither(CompletionStage other, } /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * exceptionally, is composed using the results of the supplied - * function applied to this stage's exception, using this stage's + * function applied to {@code this} stage's exception, using {@code this} stage's * default asynchronous execution facility. * * @implSpec The default implementation invokes {@link #handle}, @@ -937,7 +951,7 @@ public CompletionStage runAfterEither(CompletionStage other, * #thenCompose} for result. * * @param fn the function to use to compute the returned - * CompletionStage if this CompletionStage completed exceptionally + * CompletionStage if {@code this} CompletionStage completed exceptionally * @return the new CompletionStage * @since 12 */ @@ -951,9 +965,9 @@ public CompletionStage runAfterEither(CompletionStage other, } /** - * Returns a new CompletionStage that, when this stage completes + * Returns a new CompletionStage that, when {@code this} stage completes * exceptionally, is composed using the results of the supplied - * function applied to this stage's exception, using the + * function applied to {@code this} stage's exception, using the * supplied Executor. * * @implSpec The default implementation invokes {@link #handle}, @@ -961,7 +975,7 @@ public CompletionStage runAfterEither(CompletionStage other, * #thenCompose} for result. * * @param fn the function to use to compute the returned - * CompletionStage if this CompletionStage completed exceptionally + * CompletionStage if {@code this} CompletionStage completed exceptionally * @param executor the executor to use for asynchronous execution * @return the new CompletionStage * @since 12 @@ -978,9 +992,9 @@ public CompletionStage runAfterEither(CompletionStage other, /** * Returns a {@link CompletableFuture} maintaining the same - * completion properties as this stage. If this stage is already a - * CompletableFuture, this method may return this stage itself. - * Otherwise, invocation of this method may be equivalent in + * completion properties as {@code this} stage. If {@code this} stage is already a + * CompletableFuture, method {@code toCompletableFuture} may return {@code this} stage itself. + * Otherwise, invocation may be equivalent in * effect to {@code thenApply(x -> x)}, but returning an instance * of type {@code CompletableFuture}. * diff --git a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java index 8734980cf808a..b9df942fbfd45 100644 --- a/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java +++ b/src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java @@ -147,7 +147,7 @@ *

Like {@link Hashtable} but unlike {@link HashMap}, this class * does not allow {@code null} to be used as a key or value. * - *

ConcurrentHashMaps support a set of sequential and parallel bulk + *

ConcurrentHashMaps support a set of sequential and parallel bulk * operations that, unlike most {@link Stream} methods, are designed * to be safely, and often sensibly, applied even with maps that are * being concurrently updated by other threads; for example, when @@ -3704,7 +3704,7 @@ final int batchFor(long b) { } /** - * Performs the given action for each (key, value). + * Performs the given {@linkplain ##Bulk bulk} action for each (key, value). * * @param parallelismThreshold the (estimated) number of elements * needed for this operation to be executed in parallel @@ -3720,7 +3720,7 @@ public void forEach(long parallelismThreshold, } /** - * Performs the given action for each non-null transformation + * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation * of each (key, value). * * @param parallelismThreshold the (estimated) number of elements @@ -3743,7 +3743,7 @@ public void forEach(long parallelismThreshold, } /** - * Returns a non-null result from applying the given search + * Returns a non-null result from applying the given {@linkplain ##Bulk bulk} search * function on each (key, value), or null if none. Upon * success, further element processing is suppressed and the * results of any other parallel invocations of the search @@ -3767,7 +3767,7 @@ public U search(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation * of all (key, value) pairs using the given reducer to * combine values, or null if none. * @@ -3793,7 +3793,7 @@ public U reduce(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation * of all (key, value) pairs using the given reducer to * combine values, and the given basis as an identity value. * @@ -3819,7 +3819,7 @@ public double reduceToDouble(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation * of all (key, value) pairs using the given reducer to * combine values, and the given basis as an identity value. * @@ -3845,7 +3845,7 @@ public long reduceToLong(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation * of all (key, value) pairs using the given reducer to * combine values, and the given basis as an identity value. * @@ -3871,7 +3871,7 @@ public int reduceToInt(long parallelismThreshold, } /** - * Performs the given action for each key. + * Performs the given {@linkplain ##Bulk bulk} action for each key. * * @param parallelismThreshold the (estimated) number of elements * needed for this operation to be executed in parallel @@ -3887,7 +3887,7 @@ public void forEachKey(long parallelismThreshold, } /** - * Performs the given action for each non-null transformation + * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation * of each key. * * @param parallelismThreshold the (estimated) number of elements @@ -3910,7 +3910,7 @@ public void forEachKey(long parallelismThreshold, } /** - * Returns a non-null result from applying the given search + * Returns a non-null result from applying the given {@linkplain ##Bulk bulk} search * function on each key, or null if none. Upon success, * further element processing is suppressed and the results of * any other parallel invocations of the search function are @@ -3934,7 +3934,7 @@ public U searchKeys(long parallelismThreshold, } /** - * Returns the result of accumulating all keys using the given + * Returns the result of {@linkplain ##Bulk bulk} accumulating all keys using the given * reducer to combine values, or null if none. * * @param parallelismThreshold the (estimated) number of elements @@ -3953,7 +3953,7 @@ public K reduceKeys(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all keys using the given reducer to combine values, or * null if none. * @@ -3979,7 +3979,7 @@ public U reduceKeys(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all keys using the given reducer to combine values, and * the given basis as an identity value. * @@ -4005,7 +4005,7 @@ public double reduceKeysToDouble(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all keys using the given reducer to combine values, and * the given basis as an identity value. * @@ -4031,7 +4031,7 @@ public long reduceKeysToLong(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all keys using the given reducer to combine values, and * the given basis as an identity value. * @@ -4057,7 +4057,7 @@ public int reduceKeysToInt(long parallelismThreshold, } /** - * Performs the given action for each value. + * Performs the given {@linkplain ##Bulk bulk} action for each value. * * @param parallelismThreshold the (estimated) number of elements * needed for this operation to be executed in parallel @@ -4074,7 +4074,7 @@ public void forEachValue(long parallelismThreshold, } /** - * Performs the given action for each non-null transformation + * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation * of each value. * * @param parallelismThreshold the (estimated) number of elements @@ -4097,7 +4097,7 @@ public void forEachValue(long parallelismThreshold, } /** - * Returns a non-null result from applying the given search + * Returns a non-null result from {@linkplain ##Bulk bulk} applying the given search * function on each value, or null if none. Upon success, * further element processing is suppressed and the results of * any other parallel invocations of the search function are @@ -4121,7 +4121,7 @@ public U searchValues(long parallelismThreshold, } /** - * Returns the result of accumulating all values using the + * Returns the result of {@linkplain ##Bulk bulk} accumulating all values using the * given reducer to combine values, or null if none. * * @param parallelismThreshold the (estimated) number of elements @@ -4139,7 +4139,7 @@ public V reduceValues(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all values using the given reducer to combine values, or * null if none. * @@ -4165,7 +4165,7 @@ public U reduceValues(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all values using the given reducer to combine values, * and the given basis as an identity value. * @@ -4191,7 +4191,7 @@ public double reduceValuesToDouble(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all values using the given reducer to combine values, * and the given basis as an identity value. * @@ -4217,7 +4217,7 @@ public long reduceValuesToLong(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all values using the given reducer to combine values, * and the given basis as an identity value. * @@ -4243,7 +4243,7 @@ public int reduceValuesToInt(long parallelismThreshold, } /** - * Performs the given action for each entry. + * Performs the given {@linkplain ##Bulk bulk} action for each entry. * * @param parallelismThreshold the (estimated) number of elements * needed for this operation to be executed in parallel @@ -4258,7 +4258,7 @@ public void forEachEntry(long parallelismThreshold, } /** - * Performs the given action for each non-null transformation + * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation * of each entry. * * @param parallelismThreshold the (estimated) number of elements @@ -4281,7 +4281,7 @@ public void forEachEntry(long parallelismThreshold, } /** - * Returns a non-null result from applying the given search + * Returns a non-null result from {@linkplain ##Bulk bulk} applying the given search * function on each entry, or null if none. Upon success, * further element processing is suppressed and the results of * any other parallel invocations of the search function are @@ -4305,7 +4305,7 @@ public U searchEntries(long parallelismThreshold, } /** - * Returns the result of accumulating all entries using the + * Returns the result of {@linkplain ##Bulk bulk} accumulating all entries using the * given reducer to combine values, or null if none. * * @param parallelismThreshold the (estimated) number of elements @@ -4323,7 +4323,7 @@ public Map.Entry reduceEntries(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all entries using the given reducer to combine values, * or null if none. * @@ -4349,7 +4349,7 @@ public U reduceEntries(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all entries using the given reducer to combine values, * and the given basis as an identity value. * @@ -4375,7 +4375,7 @@ public double reduceEntriesToDouble(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all entries using the given reducer to combine values, * and the given basis as an identity value. * @@ -4401,7 +4401,7 @@ public long reduceEntriesToLong(long parallelismThreshold, } /** - * Returns the result of accumulating the given transformation + * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation * of all entries using the given reducer to combine values, * and the given basis as an identity value. * diff --git a/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java b/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java index 87e498d9c247a..ca78c25462487 100644 --- a/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java +++ b/src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java @@ -44,7 +44,10 @@ * useful in programs involving a fixed sized party of threads that * must occasionally wait for each other. The barrier is called * cyclic because it can be re-used after the waiting threads - * are released. + * are released. If you need support for variable numbers of parties + * per cycle, alternate actions on exceptions, termination control, + * contention control, or status monitoring, use the more flexible + * {@link Phaser} class. * *

A {@code CyclicBarrier} supports an optional {@link Runnable} command * that is run once per barrier point, after the last thread in the party diff --git a/src/java.base/share/classes/java/util/concurrent/ExecutorService.java b/src/java.base/share/classes/java/util/concurrent/ExecutorService.java index 0d4acf8913e04..f899b56b28883 100644 --- a/src/java.base/share/classes/java/util/concurrent/ExecutorService.java +++ b/src/java.base/share/classes/java/util/concurrent/ExecutorService.java @@ -56,7 +56,9 @@ * *

Method {@code submit} extends base method {@link * Executor#execute(Runnable)} by creating and returning a {@link Future} - * that can be used to cancel execution and/or wait for completion. + * that can be used to cancel execution and/or wait for completion; + * also reporting exceptions that would otherwise be uncaught + * using method {@code execute}. * Methods {@code invokeAny} and {@code invokeAll} perform the most * commonly useful forms of bulk execution, executing a collection of * tasks and then waiting for at least one, or all, to diff --git a/src/java.base/share/classes/java/util/concurrent/Executors.java b/src/java.base/share/classes/java/util/concurrent/Executors.java index ba7c2e1efeebe..ef3d634801090 100644 --- a/src/java.base/share/classes/java/util/concurrent/Executors.java +++ b/src/java.base/share/classes/java/util/concurrent/Executors.java @@ -306,7 +306,7 @@ public static ScheduledExecutorService newSingleThreadScheduledExecutor(ThreadFa } /** - * Creates a thread pool that can schedule commands to run after a + * Creates a fixed-size thread pool that can schedule commands to run after a * given delay, or to execute periodically. * @param corePoolSize the number of threads to keep in the pool, * even if they are idle @@ -318,7 +318,7 @@ public static ScheduledExecutorService newScheduledThreadPool(int corePoolSize) } /** - * Creates a thread pool that can schedule commands to run after a + * Creates a fixed-size thread pool that can schedule commands to run after a * given delay, or to execute periodically. * @param corePoolSize the number of threads to keep in the pool, * even if they are idle diff --git a/src/java.base/share/classes/java/util/concurrent/Flow.java b/src/java.base/share/classes/java/util/concurrent/Flow.java index 1aefaea43b0e3..16b2ba5e9d809 100644 --- a/src/java.base/share/classes/java/util/concurrent/Flow.java +++ b/src/java.base/share/classes/java/util/concurrent/Flow.java @@ -60,7 +60,8 @@ * TRUE} item to a single subscriber. Because the subscriber receives * only a single item, this class does not use buffering and ordering * control required in most implementations (for example {@link - * SubmissionPublisher}). + * SubmissionPublisher}), and omits some error processing needed to + * fully conform to the Reactive Streams specification. * * 

 {@code
  * class OneShotPublisher implements Publisher {
diff --git a/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java b/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
index a7821921bc911..482fe3cf80136 100644
--- a/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
+++ b/src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
@@ -140,7 +140,7 @@
  * tasks, as well as method {@link #submitWithTimeout} to cancel tasks
  * that take too long. The scheduled functions or actions may create
  * and invoke other {@linkplain ForkJoinTask ForkJoinTasks}. Delayed
- * actions become enabled and behave as ordinary submitted
+ * actions become enabled for execution and behave as ordinary submitted
  * tasks when their delays elapse.  Scheduling methods return
  * {@linkplain ForkJoinTask ForkJoinTasks} that implement the {@link
  * ScheduledFuture} interface. Resource exhaustion encountered after
@@ -153,7 +153,7 @@
  * to disable all delayed tasks upon shutdown, and method {@link
  * #shutdownNow} may be used to instead unconditionally initiate pool
  * termination. Monitoring methods such as {@link #getQueuedTaskCount}
- * do not include scheduled tasks that are not yet enabled to execute,
+ * do not include scheduled tasks that are not yet enabled for execution,
  * which are reported separately by method {@link
  * #getDelayedTaskCount}.
  *
@@ -3505,7 +3505,7 @@ final  ScheduledForkJoinTask scheduleDelayedTask(ScheduledForkJoinTask
     }
 
     /**
-     * Submits a one-shot task that becomes enabled after the given
+     * Submits a one-shot task that becomes enabled for execution after the given
      * delay.  At that point it will execute unless explicitly
      * cancelled, or fail to execute (eventually reporting
      * cancellation) when encountering resource exhaustion, or the
@@ -3533,7 +3533,7 @@ public ScheduledFuture schedule(Runnable command,
     }
 
     /**
-     * Submits a value-returning one-shot task that becomes enabled
+     * Submits a value-returning one-shot task that becomes enabled for execution
      * after the given delay. At that point it will execute unless
      * explicitly cancelled, or fail to execute (eventually reporting
      * cancellation) when encountering resource exhaustion, or the
@@ -3562,7 +3562,7 @@ public  ScheduledFuture schedule(Callable callable,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -3616,7 +3616,7 @@ public ScheduledFuture scheduleAtFixedRate(Runnable command,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/Future.java b/src/java.base/share/classes/java/util/concurrent/Future.java
index c6f3036c2d28f..2ac837d72701a 100644
--- a/src/java.base/share/classes/java/util/concurrent/Future.java
+++ b/src/java.base/share/classes/java/util/concurrent/Future.java
@@ -50,6 +50,26 @@
  * declare types of the form {@code Future} and
  * return {@code null} as a result of the underlying task.
  *
+ * 
Cancellation of a Future need not abruptly terminate its
+ * computation. Method {@code cancel} causes {@code isCancelled()} to
+ * return {@code true} unless already {@code isDone()}; in either case
+ * {@code isDone()} subsequently reports {@code true}. This suppresses
+ * execution by an {@link ExecutorService} if not already started.
+ * There are several options for suppressing unnecessary computation
+ * or unblocking a running Future that will not generate a
+ * result. When task bodies are simple and short, no special attention
+ * is warranted.  Computational methods in Future-aware code bodies
+ * (for example {@link ForkJoinTask}, {@link FutureTask}) may inspect
+ * their own {@code isDone()} status before or while engaging in
+ * expensive computations. In blocking I/O or communication contexts,
+ * the optional {@code mayInterruptIfRunning} argument of {@code
+ * cancel} may be used to support conventions that tasks should
+ * unblock and exit when {@link Thread#interrupted}, whether checked
+ * inside a task body or as a response to an {@link
+ * InterruptedException}.  It is still preferable to additionally
+ * check {@code isDone()} status when possible to avoid unintended
+ * effects of other uses of {@link Thread#interrupt}.
+ *
  * 
Sample Usage (Note that the following classes are all
  * made-up.)
  *
diff --git a/src/java.base/share/classes/java/util/concurrent/FutureTask.java b/src/java.base/share/classes/java/util/concurrent/FutureTask.java
index b905e71aeef95..2ec976291054e 100644
--- a/src/java.base/share/classes/java/util/concurrent/FutureTask.java
+++ b/src/java.base/share/classes/java/util/concurrent/FutureTask.java
@@ -285,7 +285,9 @@ protected void done() { }
      * this future has already been set or has been cancelled.
      *
      * 
This method is invoked internally by the {@link #run} method
-     * upon successful completion of the computation.
+     * upon successful completion of the computation. Invocation in
+     * other contexts has undefined effects. Any override of this
+     * method in subclasses should include {@code super.set(v)}.
      *
      * @param v the value
      */
diff --git a/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java b/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
index b6b088ae7cd82..8585cfe108297 100644
--- a/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
+++ b/src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
@@ -47,8 +47,9 @@
  */
 public interface RunnableFuture extends Runnable, Future {
     /**
-     * Sets this Future to the result of its computation
-     * unless it has been cancelled.
+     * Sets this Future to the result of its computation unless it has
+     * been cancelled (or has already been invoked, in which case
+     * effects are undefined).
      */
     void run();
 }
diff --git a/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java b/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
index 4d63ffae4bb44..034d98687c257 100644
--- a/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
+++ b/src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
@@ -40,10 +40,12 @@
  * delay, or to execute periodically.
  *
  * 
The {@code schedule} methods create tasks with various delays
- * and return a task object that can be used to cancel or check
- * execution. The {@code scheduleAtFixedRate} and
- * {@code scheduleWithFixedDelay} methods create and execute tasks
- * that run periodically until cancelled.
+ * and return {@link ScheduledFuture} objects that can be used to cancel or check
+ * execution. When delays elapse, tasks are enabled for execution and
+ * behave in accord with other {@link ExecutorService} tasks, except
+ * that {@code scheduleAtFixedRate} and {@code scheduleWithFixedDelay}
+ * methods create and execute tasks that run periodically until
+ * cancelled.
  *
  * 
Commands submitted using the {@link Executor#execute(Runnable)}
  * and {@link ExecutorService} {@code submit} methods are scheduled
@@ -91,7 +93,7 @@
 public interface ScheduledExecutorService extends ExecutorService {
 
     /**
-     * Submits a one-shot task that becomes enabled after the given delay.
+     * Submits a one-shot task that becomes enabled for execution after the given delay.
      *
      * @param command the task to execute
      * @param delay the time from now to delay execution
@@ -107,7 +109,7 @@ public ScheduledFuture schedule(Runnable command,
                                        long delay, TimeUnit unit);
 
     /**
-     * Submits a value-returning one-shot task that becomes enabled
+     * Submits a value-returning one-shot task that becomes enabled for execution
      * after the given delay.
      *
      * @param callable the function to execute
@@ -123,7 +125,7 @@ public  ScheduledFuture schedule(Callable callable,
                                            long delay, TimeUnit unit);
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -167,7 +169,7 @@ public ScheduledFuture scheduleAtFixedRate(Runnable command,
                                                   TimeUnit unit);
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java b/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
index 94f40ccf6f516..23398aeae2813 100644
--- a/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
+++ b/src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
@@ -57,7 +57,7 @@
  * capabilities of {@link ThreadPoolExecutor} (which this class
  * extends) are required.
  *
- * 
Delayed tasks execute no sooner than they are enabled, but
+ * 
Delayed tasks execute no sooner than they are enabled for execution, but
  * without any real-time guarantees about when, after they are
  * enabled, they will commence. Tasks scheduled for exactly the same
  * execution time are enabled in first-in-first-out (FIFO) order of
@@ -568,7 +568,7 @@ public  ScheduledFuture schedule(Callable callable,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given period;
      * that is, executions will commence after
      * {@code initialDelay}, then {@code initialDelay + period}, then
@@ -621,7 +621,7 @@ public ScheduledFuture scheduleAtFixedRate(Runnable command,
     }
 
     /**
-     * Submits a periodic action that becomes enabled first after the
+     * Submits a periodic action that becomes enabled for execution first after the
      * given initial delay, and subsequently with the given delay
      * between the termination of one execution and the commencement of
      * the next.
diff --git a/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java b/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
index 3a8f37466374c..f793d2bcabdf2 100644
--- a/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
+++ b/src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
@@ -162,8 +162,8 @@
  *     (this.subscription = subscription).request(1);
  *   }
  *   public void onNext(S item) {
- *     subscription.request(1);
  *     submit(function.apply(item));
+ *     subscription.request(1);
  *   }
  *   public void onError(Throwable ex) { closeExceptionally(ex); }
  *   public void onComplete() { close(); }
@@ -602,9 +602,11 @@ public int offer(T item, long timeout, TimeUnit unit,
     /**
      * Unless already closed, issues {@link
      * Flow.Subscriber#onComplete() onComplete} signals to current
-     * subscribers, and disallows subsequent attempts to publish.
-     * Upon return, this method does NOT guarantee that all
-     * subscribers have yet completed.
+     * subscribers, and disallows subsequent attempts to publish. To
+     * ensure uniform ordering among subscribers, this method may
+     * await completion of in-progress offers.  Upon return, this
+     * method does NOT guarantee that all subscribers have
+     * yet completed.
      */
     public void close() {
         ReentrantLock lock = this.lock;
diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
index f02aa9f593192..d116fb9b22bcc 100644
--- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
+++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
@@ -398,6 +398,8 @@ else if (s == MICRO_SCALE)
      * @param obj the object to wait on
      * @param timeout the maximum time to wait. If less than
      * or equal to zero, do not wait at all.
+     * @throws  IllegalMonitorStateException  if the current thread is not
+     *               the owner of the object's monitor.
      * @throws InterruptedException if interrupted while waiting
      */
     public void timedWait(Object obj, long timeout)
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
index e01b3ec7d50f9..f947eb4f7db88 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
@@ -46,10 +46,11 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile int} fields of designated classes.
- * This class is designed for use in atomic data structures in which
- * several fields of the same node are independently subject to atomic
- * updates.
+ * designated non-static {@code volatile int} fields of designated
+ * classes, providing a subset of the functionality of class {@link
+ * VarHandle} that should be used instead.  This class is designed for
+ * use in atomic data structures in which several fields of the same
+ * node are independently subject to atomic updates.
  *
  * 
Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
index 57722f333711a..b31a8edf53a46 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
@@ -46,10 +46,11 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile long} fields of designated classes.
- * This class is designed for use in atomic data structures in which
- * several fields of the same node are independently subject to atomic
- * updates.
+ * designated non-static {@code volatile long} fields of designated
+ * classes, providing a subset of the functionality of class {@link
+ * VarHandle} that should be used instead.  This class is designed for
+ * use in atomic data structures in which several fields of the same
+ * node are independently subject to atomic updates.
  *
  * 
Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
diff --git a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
index 1c0c6d0afd070..e3ca4830d5a21 100644
--- a/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
+++ b/src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
@@ -46,11 +46,12 @@
 
 /**
  * A reflection-based utility that enables atomic updates to
- * designated {@code volatile} reference fields of designated
- * classes.  This class is designed for use in atomic data structures
- * in which several reference fields of the same node are
- * independently subject to atomic updates. For example, a tree node
- * might be declared as
+ * designated non-static {@code volatile} reference fields of
+ * designated classes, providing a subset of the functionality of
+ * class {@link VarHandle} that should be used instead.  This class
+ * may be used in atomic data structures in which several reference
+ * fields of the same node are independently subject to atomic
+ * updates. For example, a tree node might be declared as
  *
  * 
 {@code
  * class Node {
@@ -68,6 +69,26 @@
  *   // ... and so on
  * }}

  *
+ * However, it is preferable to use {@link VarHandle}:
+ * 
 {@code
+ * import java.lang.invoke.VarHandle;
+ * import java.lang.invoke.MethodHandles;
+ * class Node {
+ *  private volatile Node left, right;
+ *  private static final VarHandle LEFT, RIGHT;
+ *  Node getLeft() { return left; }
+ *  boolean compareAndSetLeft(Node expect, Node update) {
+ *    return LEFT.compareAndSet(this, expect, update);
+ *  }
+ *  // ... and so on
+ *  static { try {
+ *    MethodHandles.Lookup l = MethodHandles.lookup();
+ *    LEFT  = l.findVarHandle(Node.class, "left", Node.class);
+ *    RIGHT = l.findVarHandle(Node.class, "right", Node.class);
+ *   } catch (ReflectiveOperationException e) {
+ *     throw new ExceptionInInitializerError(e);
+ * }}}}

+ *
  * 
Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.
  * Because this class cannot ensure that all uses of the field
diff --git a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
index 3e0b293380f5f..536996fd27334 100644
--- a/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
+++ b/src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
@@ -97,6 +97,10 @@
  * perform reads under read locks.  If a reader tries to acquire the
  * write lock it will never succeed.
  *
+ * 
Note: If you do not rely on reentrancy, you may find that {@link
+ * StampedLock} offers better performance, as in: {@code ReadWriteLock
+ * lock = new StampedLock().asReadWriteLock()}.
+ *
  * 
  • Lock downgrading
  * 
    Reentrancy also allows downgrading from the write lock to a read lock,
  * by acquiring the write lock, then the read lock and then releasing the
@@ -734,11 +738,13 @@ protected ReadLock(ReentrantReadWriteLock lock) {
          * Acquires the read lock.
          *
          * 
    Acquires the read lock if the write lock is not held by
-         * another thread and returns immediately.
+         * any thread and returns immediately.
          *
-         * 
    If the write lock is held by another thread then
-         * the current thread becomes disabled for thread scheduling
-         * purposes and lies dormant until the read lock has been acquired.
+         * 
    If the write lock is held by any thread or the fairness
+         * policy prohibits acquisition of the read lock at this time,
+         * then the current thread becomes disabled for thread
+         * scheduling purposes and lies dormant until the read lock
+         * has been acquired.
          */
         public void lock() {
             sync.acquireShared(1);
@@ -749,11 +755,13 @@ public void lock() {
          * {@linkplain Thread#interrupt interrupted}.
          *
          * 
    Acquires the read lock if the write lock is not held
-         * by another thread and returns immediately.
+         * by any thread and returns immediately.
          *
-         * 
    If the write lock is held by another thread then the
-         * current thread becomes disabled for thread scheduling
-         * purposes and lies dormant until one of two things happens:
+         * 
    If the write lock is held by any thread or the fairness
+         * policy prohibits acquisition of the read lock at this time,
+         * then the current thread becomes disabled for thread
+         * scheduling purposes and lies dormant until one of two
+         * things happens:
          *
          * 
      
          *
@@ -794,7 +802,7 @@ public void lockInterruptibly() throws InterruptedException {
          * another thread at the time of invocation.
          *
          * 
      Acquires the read lock if the write lock is not held by
-         * another thread and returns immediately with the value
+         * any thread and returns immediately with the value
          * {@code true}. Even when this lock has been set to use a
          * fair ordering policy, a call to {@code tryLock()}
          * will immediately acquire the read lock if it is
@@ -806,7 +814,7 @@ public void lockInterruptibly() throws InterruptedException {
          * tryLock(0, TimeUnit.SECONDS)} which is almost equivalent
          * (it also detects interruption).
          *
-         * 
      If the write lock is held by another thread then
+         * 
      If the write lock is held by any thread then
          * this method will return immediately with the value
          * {@code false}.
          *
diff --git a/src/java.base/share/classes/java/util/concurrent/package-info.java b/src/java.base/share/classes/java/util/concurrent/package-info.java
index dd0c8f79bc024..f237017799d9f 100644
--- a/src/java.base/share/classes/java/util/concurrent/package-info.java
+++ b/src/java.base/share/classes/java/util/concurrent/package-info.java
@@ -222,7 +222,9 @@
  * 
    • they are guaranteed to traverse elements as they existed upon
  * construction exactly once, and may (but are not guaranteed to)
  * reflect any modifications subsequent to construction.
- * 
    
+ * 
  •  These properties extend to other iteration-based
+ * operations. In particular, {@link Object#equals} is almost never
+ * useful unless both collections are known to be quiescent.  
  *
  * 
    Memory Consistency Properties
    
  *