8359919: Minor java.util.concurrent doc improvements

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}.
  *
  * <p><b>Extension example.</b> Here is a sketch of a class
  * that customizes {@link ThreadPoolExecutor} to use

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
  * <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

src/java.base/share/classes/java/util/concurrent/ExecutorService.java

@@ -56,7 +56,9 @@
  *
  * <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

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

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.
  *
  * <pre> {@code
  * class OneShotPublisher implements Publisher<Boolean> {

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 <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 @@
  * 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 <T> ScheduledForkJoinTask<T> scheduleDelayedTask(ScheduledForkJoinTask<T>
     }
 
     /**
-     * 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 <V> ScheduledFuture<V> schedule(Callable<V> 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.

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.
  *
+ * <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.)
  *

src/java.base/share/classes/java/util/concurrent/RunnableFuture.java

@@ -47,8 +47,9 @@
  */
 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();
 }

src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java

@@ -40,10 +40,12 @@
  * 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 @@
 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 <V> ScheduledFuture<V> schedule(Callable<V> 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.

src/java.base/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java

@@ -57,7 +57,7 @@
  * 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 <V> ScheduledFuture<V> schedule(Callable<V> 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.

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 <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;

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)

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.
  *
  * <p>Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.

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.
  *
  * <p>Note that the guarantees of the {@code compareAndSet}
  * method in this class are weaker than in other atomic classes.

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
  *
  * <pre> {@code
  * class Node {
@@ -68,6 +69,26 @@
  *   // ... 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