infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-02-02 14:38:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

8359919: Minor java.util.concurrent doc improvements

Browse Source 
8187775: AtomicReferenceFieldUpdater does not support static fields
8254060: SubmissionPublisher close hangs if a publication is pending
8210149: Example in JavaDoc for java.util.concurrent.Flow violates Reactive Streams spec
8199501: Improve documentation of CompletableFuture, CompletionStage
8233050: CompletableFuture `whenComplete` and `thenApply` change exceptional result
8210312: JavaDoc example in SubmissionPublisher will potentially crash
8292365: CompletableFuture and CompletionStage should document Memory Model guarantees
8356304: Define "enabled" in ScheduledExecutorService
8353155: FutureTask#run(): doc implies synchronous, implementation is async
8186959: Clarify that Executors.newScheduledThreadPool() is fixed-size
8190889: TimeUnit.wait should document IllegalMonitorStateException
6351533: CyclicBarrier reset() should return the number of awaiters
6317534: CyclicBarrier should have a cancel() method
8195628: Documentation for lock(), trylock(), lockInterruptibly​()  of ReentrantReadWriteLock.WriteLock needs to be corrected
8333172: Document a recommendation to use VarHandles instead of java.util.concurrent.atomic.*FieldUpdater
6374942: Improve thread safety of collection .equals() methods
7176957: ExecutorService submit method javaDoc enhancement
8172177: Improve documentation for CompletionException handling
6714849: ReentrantReadWriteLock: Abnormal behavior in non-fair mode
6625724: Allow ReentrantReadWriteLock to not track per-thread read holds
6526284: Improve AbstractExecutorService javadoc
8137156: Javadoc for Future is misleading with respect to cancellation
6663476: FutureTask.get() may return null if set() is not called from run()
8311131: ConcurrentHashMap.forEachKey parallelismThreshold description could be clearer

Reviewed-by: alanb
This commit is contained in:
Doug Lea 2025-06-26 12:04:42 +00:00
parent 5a1301df19
commit ff24088c86
20 changed files with 304 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/java.base/share/classes/java/util/concurrent/AbstractExecutorService.java
View File

@ -44,16 +44,16 @@ import java.util.List;
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}.
*
* <p><b>Extension example.</b> Here is a sketch of a class
* that customizes {@link ThreadPoolExecutor} to use

268
src/java.base/share/classes/java/util/concurrent/CompletionStage.java
View File

@ -43,7 +43,7 @@ import java.util.function.Function;
/**
* 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 @@ import java.util.function.Function;
* 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 <em>both</em> of two stages, and both
* complete exceptionally, then the CompletionException may correspond
* to either one of these exceptions. If a stage is dependent on
* <em>either</em> 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
* <em>both</em> of two stages, and both complete exceptionally, then
* the CompletionException may correspond to either one of these
* exceptions. If a stage is dependent on <em>either</em> 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)}.
*
* </ul>
*
@ -137,7 +144,7 @@ import java.util.function.Function;
* }
* }}</pre>
*
* <p>This interface does not define methods for initially creating,
* <p>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 @@ import java.util.function.Function;
* enables interoperability among different implementations of this
* interface by providing a common conversion type.
*
* <p>Memory consistency effects: Actions in a thread prior to the
* submission of a computation producing a {@code CompletionStage} <a
* href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
* that computation begins. And actions taken by {@code
* CompletionStage x} <i>happen-before</i> actions of any dependent
* stage subsequent to {@code x}'s completion.
*
* @param <T> the type of values the stage produces or consumes
*
* @author Doug Lea
@ -153,8 +167,8 @@ import java.util.function.Function;
public interface CompletionStage<T> {
/**
* 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.
*
* <p>This method is analogous to
@ -172,9 +186,9 @@ public interface CompletionStage<T> {
public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> 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<T> {
(Function<? super T,? extends U> 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<T> {
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<T> {
public CompletionStage<Void> thenAccept(Consumer<? super T> 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<T> {
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> 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<T> {
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> 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 interface CompletionStage<T> {
public CompletionStage<Void> 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 interface CompletionStage<T> {
public CompletionStage<Void> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
BiFunction<? super T,? super U,? extends V> 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 interface CompletionStage<T> {
BiFunction<? super T,? super U,? extends V> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
BiConsumer<? super T, ? super U> 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 interface CompletionStage<T> {
BiConsumer<? super T, ? super U> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
public CompletionStage<Void> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
Function<? super T, U> 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 interface CompletionStage<T> {
Function<? super T, U> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
Consumer<? super T> 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 interface CompletionStage<T> {
Consumer<? super T> 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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
* Returns a new CompletionStage that is completed with the same
* value as the CompletionStage returned by the given function.
*
* <p>When this stage completes normally, the given function is
* invoked with this stage's result as the argument, returning
* <p>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.
*
* <p>To ensure progress, the supplied function must arrange
@ -652,13 +666,13 @@ public interface CompletionStage<T> {
/**
* 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.
*
* <p>When this stage completes normally, the given function is
* invoked with this stage's result as the argument, returning
* <p>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.
*
* <p>To ensure progress, the supplied function must arrange
@ -679,10 +693,10 @@ public interface CompletionStage<T> {
* value as the CompletionStage returned by the given function,
* executed using the supplied Executor.
*
* <p>When this stage completes normally, the given function is
* invoked with this stage's result as the argument, returning
* <p>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.
*
* <p>To ensure progress, the supplied function must arrange
@ -701,13 +715,13 @@ public interface CompletionStage<T> {
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.
*
* <p>When this stage is complete, the given function is invoked
* <p>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 interface CompletionStage<T> {
(BiFunction<? super T, Throwable, ? extends U> 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.
*
* <p>When this stage is complete, the given function is invoked
* <p>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 interface CompletionStage<T> {
(BiFunction<? super T, Throwable, ? extends U> 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.
*
* <p>When this stage is complete, the given function is invoked
* <p>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 interface CompletionStage<T> {
/**
* 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.
*
* <p>When this stage is complete, the given action is invoked
* <p>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.
*
* <p>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 interface CompletionStage<T> {
/**
* 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.
*
* <p>When this stage is complete, the given action is invoked with the
* <p>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.
*
* <p>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 interface CompletionStage<T> {
/**
* 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.
*
* <p>When this stage is complete, the given action is invoked with the
* <p>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.
*
* <p>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 interface CompletionStage<T> {
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 interface CompletionStage<T> {
(Function<Throwable, ? extends T> 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 interface CompletionStage<T> {
* #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 interface CompletionStage<T> {
}
/**
* 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 interface CompletionStage<T> {
* #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 interface CompletionStage<T> {
}
/**
* 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 interface CompletionStage<T> {
}
/**
* 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 interface CompletionStage<T> {
* #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 interface CompletionStage<T> {
}
/**
* 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 interface CompletionStage<T> {
* #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 interface CompletionStage<T> {
/**
* 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}.
*

64
src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java
View File

@ -147,7 +147,7 @@ import jdk.internal.vm.annotation.Stable;
* <p>Like {@link Hashtable} but unlike {@link HashMap}, this class
* does <em>not</em> allow {@code null} to be used as a key or value.
*
* <p>ConcurrentHashMaps support a set of sequential and parallel bulk
* <p id="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 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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 class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
}
/**
* 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.
*

5
src/java.base/share/classes/java/util/concurrent/CyclicBarrier.java
View File

@ -44,7 +44,10 @@ import java.util.concurrent.locks.ReentrantLock;
* useful in programs involving a fixed sized party of threads that
* must occasionally wait for each other. The barrier is called
* <em>cyclic</em> 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.
*
* <p>A {@code CyclicBarrier} supports an optional {@link Runnable} command
* that is run once per barrier point, after the last thread in the party

4
src/java.base/share/classes/java/util/concurrent/ExecutorService.java
View File

@ -56,7 +56,9 @@ import java.util.List;
*
* <p>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

4
src/java.base/share/classes/java/util/concurrent/Executors.java
View File

@ -306,7 +306,7 @@ public final class Executors {
}
/**
* 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 final class Executors {
}
/**
* 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

3
src/java.base/share/classes/java/util/concurrent/Flow.java
View File

@ -60,7 +60,8 @@ package java.util.concurrent;
* 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.
*
* <pre> {@code
* class OneShotPublisher implements Publisher<Boolean> {

12
src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java
View File

@ -140,7 +140,7 @@ import static java.util.concurrent.DelayScheduler.ScheduledForkJoinTask;
* 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 <em>enabled</em> 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 @@ import static java.util.concurrent.DelayScheduler.ScheduledForkJoinTask;
* 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 @@ public class ForkJoinPool extends AbstractExecutorService
}
/**
* 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 class ForkJoinPool extends AbstractExecutorService
}
/**
* 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 class ForkJoinPool extends AbstractExecutorService
}
/**
* 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 class ForkJoinPool extends AbstractExecutorService
}
/**
* 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.

20
src/java.base/share/classes/java/util/concurrent/Future.java
View File

@ -50,6 +50,26 @@ package java.util.concurrent;
* declare types of the form {@code Future<?>} and
* return {@code null} as a result of the underlying task.
*
* <p>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}.
*
* <p><b>Sample Usage</b> (Note that the following classes are all
* made-up.)
*

4
src/java.base/share/classes/java/util/concurrent/FutureTask.java
View File

@ -285,7 +285,9 @@ public class FutureTask<V> implements RunnableFuture<V> {
* this future has already been set or has been cancelled.
*
* <p>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
*/

5
src/java.base/share/classes/java/util/concurrent/RunnableFuture.java
View File

@ -47,8 +47,9 @@ package java.util.concurrent;
*/
public interface RunnableFuture<V> extends Runnable, Future<V> {
/**
* 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();
}

18
src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java
View File

@ -40,10 +40,12 @@ package java.util.concurrent;
* delay, or to execute periodically.
*
* <p>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.
*
* <p>Commands submitted using the {@link Executor#execute(Runnable)}
* and {@link ExecutorService} {@code submit} methods are scheduled
@ -91,7 +93,7 @@ package java.util.concurrent;
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 interface ScheduledExecutorService extends ExecutorService {
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 interface ScheduledExecutorService extends ExecutorService {
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 interface ScheduledExecutorService extends ExecutorService {
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.

6
src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java
View File

@ -57,7 +57,7 @@ import java.util.concurrent.locks.ReentrantLock;
* capabilities of {@link ThreadPoolExecutor} (which this class
* extends) are required.
*
* <p>Delayed tasks execute no sooner than they are enabled, but
* <p>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 class ScheduledThreadPoolExecutor
}
/**
* 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 class ScheduledThreadPoolExecutor
}
/**
* 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.

10
src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java
View File

@ -162,8 +162,8 @@ import static java.util.concurrent.Flow.Subscription;
* (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 class SubmissionPublisher<T> implements Publisher<T>,
/**
* Unless already closed, issues {@link
* Flow.Subscriber#onComplete() onComplete} signals to current
* subscribers, and disallows subsequent attempts to publish.
* Upon return, this method does <em>NOT</em> 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 <em>NOT</em> guarantee that all subscribers have
* yet completed.
*/
public void close() {
ReentrantLock lock = this.lock;

2
src/java.base/share/classes/java/util/concurrent/TimeUnit.java
View File

@ -398,6 +398,8 @@ public enum TimeUnit {
* @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)

9
src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
View File

@ -46,10 +46,11 @@ import java.lang.invoke.VarHandle;
/**
* 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.
*
* <p>Note that the guarantees of the {@code compareAndSet}
* method in this class are weaker than in other atomic classes.

9
src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
View File

@ -46,10 +46,11 @@ import java.lang.invoke.VarHandle;
/**
* 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.
*
* <p>Note that the guarantees of the {@code compareAndSet}
* method in this class are weaker than in other atomic classes.

31
src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
View File

@ -46,11 +46,12 @@ import java.lang.invoke.VarHandle;
/**
* 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
*
* <pre> {@code
* class Node {
@ -68,6 +69,26 @@ import java.lang.invoke.VarHandle;
* // ... and so on
* }}</pre>
*
* However, it is preferable to use {@link VarHandle}:
* <pre> {@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);
* }}}}</pre>
*
* <p>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

28
src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java
View File

@ -97,6 +97,10 @@ import jdk.internal.vm.annotation.ReservedStackAccess;
* perform reads under read locks. If a reader tries to acquire the
* write lock it will never succeed.
*
* <p>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()}.
*
* <li><b>Lock downgrading</b>
* <p>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 @@ public class ReentrantReadWriteLock
* Acquires the read lock.
*
* <p>Acquires the read lock if the write lock is not held by
* another thread and returns immediately.
* any thread and returns immediately.
*
* <p>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.
* <p>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 class ReentrantReadWriteLock
* {@linkplain Thread#interrupt interrupted}.
*
* <p>Acquires the read lock if the write lock is not held
* by another thread and returns immediately.
* by any thread and returns immediately.
*
* <p>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:
* <p>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:
*
* <ul>
*
@ -794,7 +802,7 @@ public class ReentrantReadWriteLock
* another thread at the time of invocation.
*
* <p>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()}
* <em>will</em> immediately acquire the read lock if it is
@ -806,7 +814,7 @@ public class ReentrantReadWriteLock
* tryLock(0, TimeUnit.SECONDS)} which is almost equivalent
* (it also detects interruption).
*
* <p>If the write lock is held by another thread then
* <p>If the write lock is held by any thread then
* this method will return immediately with the value
* {@code false}.
*

4
src/java.base/share/classes/java/util/concurrent/package-info.java
View File

@ -222,7 +222,9 @@
* <li>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.
* </ul>
* <li> 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. </ul>
*
* <h2 id="MemoryVisibility">Memory Consistency Properties</h2>
*