more java docs

Author: mosche

server/src/main/java/org/elasticsearch/common/util/concurrent/EsExecutors.java

@@ -159,7 +159,7 @@ public static EsThreadPoolExecutor newScaling(
      * Creates a scaling {@link EsThreadPoolExecutor} using an unbounded work queue.
      * <p>
      * The {@link EsThreadPoolExecutor} scales the same way as a regular {@link ThreadPoolExecutor} until the core pool size
-     * (and at least 1) is reached: each time a task is submitted a new worker is added.
+     * (and at least 1) is reached: each time a task is submitted a new worker is added regardless if an idle worker is available.
      * <p>
      * Once having reached the core pool size, a {@link ThreadPoolExecutor} will only add a new worker if the work queue rejects
      * a task offer. Typically, using a regular unbounded queue, task offers won't ever be rejected, meaning the worker pool would never
@@ -449,6 +449,12 @@ private static <E> LinkedTransferQueue<E> newUnboundedScalingLTQueue(int corePoo
      * For that reason {@link ExecutorScalingQueue} cannot be used with executors with empty core and max pool size of 1:
      * the only available worker could time out just about at the same time as the task is appended, see
      * <a href="https://github.com/elastic/elasticsearch/issues/124667">Github #124667</a> for more details.
+     * <p>
+     * Note, configuring executors using core = max size in combination with {@code allowCoreThreadTimeOut} could be an alternative to
+     * {@link ExecutorScalingQueue}. However, the scaling behavior would be very different: Using {@link ExecutorScalingQueue}
+     * we are able to reuse idle workers if available by means of {@link ExecutorScalingQueue#tryTransfer(Object)}.
+     * If setting core = max size, the executor will add a new worker for every task submitted until reaching the core/max pool size
+     * even if there's idle workers available.
      */
     static class ExecutorScalingQueue<E> extends LinkedTransferQueue<E> {