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/ConcurrentHashMap.java

@@ -147,7 +147,7 @@
  * <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 @@ final int batchFor(long b) {
     }
 
     /**
-     * Performs the given action for each (key, value).
+     * Performs the given {@linkplain ##Bulk bulk} action for each (key, value).
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -3720,7 +3720,7 @@ public void forEach(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation
      * of each (key, value).
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3743,7 +3743,7 @@ public <U> void forEach(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from applying the given {@linkplain ##Bulk bulk} search
      * function on each (key, value), or null if none.  Upon
      * success, further element processing is suppressed and the
      * results of any other parallel invocations of the search
@@ -3767,7 +3767,7 @@ public <U> U search(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, or null if none.
      *
@@ -3793,7 +3793,7 @@ public <U> U reduce(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3819,7 +3819,7 @@ public double reduceToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3845,7 +3845,7 @@ public long reduceToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of accumulating the given {@linkplain ##Bulk bulk} transformation
      * of all (key, value) pairs using the given reducer to
      * combine values, and the given basis as an identity value.
      *
@@ -3871,7 +3871,7 @@ public int reduceToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each key.
+     * Performs the given {@linkplain ##Bulk bulk} action for each key.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -3887,7 +3887,7 @@ public void forEachKey(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation
      * of each key.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3910,7 +3910,7 @@ public <U> void forEachKey(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from applying the given {@linkplain ##Bulk bulk} search
      * function on each key, or null if none. Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -3934,7 +3934,7 @@ public <U> U searchKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all keys using the given
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating all keys using the given
      * reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -3953,7 +3953,7 @@ public K reduceKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all keys using the given reducer to combine values, or
      * null if none.
      *
@@ -3979,7 +3979,7 @@ public <U> U reduceKeys(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4005,7 +4005,7 @@ public double reduceKeysToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4031,7 +4031,7 @@ public long reduceKeysToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all keys using the given reducer to combine values, and
      * the given basis as an identity value.
      *
@@ -4057,7 +4057,7 @@ public int reduceKeysToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each value.
+     * Performs the given {@linkplain ##Bulk bulk} action for each value.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -4074,7 +4074,7 @@ public void forEachValue(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation
      * of each value.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4097,7 +4097,7 @@ public <U> void forEachValue(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from {@linkplain ##Bulk bulk} applying the given search
      * function on each value, or null if none.  Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -4121,7 +4121,7 @@ public <U> U searchValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all values using the
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating all values using the
      * given reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4139,7 +4139,7 @@ public V reduceValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all values using the given reducer to combine values, or
      * null if none.
      *
@@ -4165,7 +4165,7 @@ public <U> U reduceValues(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4191,7 +4191,7 @@ public double reduceValuesToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4217,7 +4217,7 @@ public long reduceValuesToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all values using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4243,7 +4243,7 @@ public int reduceValuesToInt(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each entry.
+     * Performs the given {@linkplain ##Bulk bulk} action for each entry.
      *
      * @param parallelismThreshold the (estimated) number of elements
      * needed for this operation to be executed in parallel
@@ -4258,7 +4258,7 @@ public void forEachEntry(long parallelismThreshold,
     }
 
     /**
-     * Performs the given action for each non-null transformation
+     * Performs the given {@linkplain ##Bulk bulk} action for each non-null transformation
      * of each entry.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4281,7 +4281,7 @@ public <U> void forEachEntry(long parallelismThreshold,
     }
 
     /**
-     * Returns a non-null result from applying the given search
+     * Returns a non-null result from {@linkplain ##Bulk bulk} applying the given search
      * function on each entry, or null if none.  Upon success,
      * further element processing is suppressed and the results of
      * any other parallel invocations of the search function are
@@ -4305,7 +4305,7 @@ public <U> U searchEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating all entries using the
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating all entries using the
      * given reducer to combine values, or null if none.
      *
      * @param parallelismThreshold the (estimated) number of elements
@@ -4323,7 +4323,7 @@ public Map.Entry<K,V> reduceEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * or null if none.
      *
@@ -4349,7 +4349,7 @@ public <U> U reduceEntries(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4375,7 +4375,7 @@ public double reduceEntriesToDouble(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *
@@ -4401,7 +4401,7 @@ public long reduceEntriesToLong(long parallelismThreshold,
     }
 
     /**
-     * Returns the result of accumulating the given transformation
+     * Returns the result of {@linkplain ##Bulk bulk} accumulating the given transformation
      * of all entries using the given reducer to combine values,
      * and the given basis as an identity value.
      *

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