8359919: Minor java.util.concurrent doc improvements

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

src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java

@@ -734,9 +734,9 @@ protected ReadLock(ReentrantReadWriteLock lock) {
          * 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
+         * <p>If the write lock is held by any thread then
          * the current thread becomes disabled for thread scheduling
          * purposes and lies dormant until the read lock has been acquired.
          */
@@ -749,9 +749,9 @@ public void lock() {
          * {@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
+         * <p>If the write lock is held by any thread then the
          * current thread becomes disabled for thread scheduling
          * purposes and lies dormant until one of two things happens:
          *
@@ -794,7 +794,7 @@ public void lockInterruptibly() throws InterruptedException {
          * 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 +806,7 @@ public void lockInterruptibly() throws InterruptedException {
          * 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}.
          *

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

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