Add documentation to thread pool and executor code

modules/repository-s3/src/test/java/org/elasticsearch/repositories/s3/RepositoryCredentialsTests.java

@@ -267,7 +267,7 @@ protected S3Repository createRepository(
         ) {
             return new S3Repository(metadata, registry, getService(), clusterService, bigArrays, recoverySettings, s3RepositoriesMetrics) {
                 @Override
-                protected void assertSnapshotOrGenericThread() {
+                protected void assertSnapshotOrStatelessPermittedThreadPool() {
                     // eliminate thread name check as we create repo manually on test/main threads
                 }
             };

modules/repository-s3/src/test/java/org/elasticsearch/repositories/s3/S3RepositoryTests.java

@@ -132,7 +132,7 @@ private S3Repository createS3Repo(RepositoryMetadata metadata) {
             S3RepositoriesMetrics.NOOP
         ) {
             @Override
-            protected void assertSnapshotOrGenericThread() {
+            protected void assertSnapshotOrStatelessPermittedThreadPool() {
                 // eliminate thread name check as we create repo manually on test/main threads
             }
         };

modules/repository-url/src/test/java/org/elasticsearch/repositories/url/URLRepositoryTests.java

@@ -43,7 +43,7 @@ private URLRepository createRepository(Settings baseSettings, RepositoryMetadata
             mock(URLHttpClient.Factory.class)
         ) {
             @Override
-            protected void assertSnapshotOrGenericThread() {
+            protected void assertSnapshotOrStatelessPermittedThreadPool() {
                 // eliminate thread name check as we create repo manually on test/main threads
             }
         };

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

@@ -33,6 +33,9 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
+/**
+ * A collection of static methods to help create different ES Executor types.
+ */
 public class EsExecutors {
 
     // although the available processors may technically change, for node sizing we use the number available at launch

server/src/main/java/org/elasticsearch/repositories/blobstore/BlobStoreRepository.java

@@ -680,7 +680,7 @@ protected BlobStore getBlobStore() {
      * maintains single lazy instance of {@link BlobContainer}
      */
     protected BlobContainer blobContainer() {
-        assertSnapshotOrGenericThread();
+        assertSnapshotOrStatelessPermittedThreadPool();
 
         if (lifecycle.started() == false) {
             throw notStartedException();
@@ -705,7 +705,7 @@ protected BlobContainer blobContainer() {
      * Public for testing.
      */
     public BlobStore blobStore() {
-        assertSnapshotOrGenericThread();
+        assertSnapshotOrStatelessPermittedThreadPool();
 
         BlobStore store = blobStore.get();
         if (store == null) {
@@ -1994,7 +1994,7 @@ public long getRestoreThrottleTimeInNanos() {
         return restoreRateLimitingTimeInNanos.count();
     }
 
-    protected void assertSnapshotOrGenericThread() {
+    protected void assertSnapshotOrStatelessPermittedThreadPool() {
         // The Stateless plugin adds custom thread pools for object store operations
         assert ThreadPool.assertCurrentThreadPool(
             ThreadPool.Names.SNAPSHOT,
@@ -3539,7 +3539,7 @@ public IndexShardSnapshotStatus.Copy getShardSnapshotStatus(SnapshotId snapshotI
 
     @Override
     public void verify(String seed, DiscoveryNode localNode) {
-        assertSnapshotOrGenericThread();
+        assertSnapshotOrStatelessPermittedThreadPool();
         if (isReadOnly()) {
             try {
                 latestIndexBlobId();

server/src/main/java/org/elasticsearch/threadpool/FixedExecutorBuilder.java

@@ -24,6 +24,9 @@
 
 /**
  * A builder for fixed executors.
+ *
+ * Builds an Executor with a static number of threads, as opposed to {@link ScalingExecutorBuilder} that dynamically scales the number of
+ * threads in the pool up and down based on request load.
  */
 public final class FixedExecutorBuilder extends ExecutorBuilder<FixedExecutorBuilder.FixedExecutorSettings> {
 

server/src/main/java/org/elasticsearch/threadpool/ScalingExecutorBuilder.java

@@ -24,6 +24,10 @@
 
 /**
  * A builder for scaling executors.
+ *
+ * The {@link #build} method will instantiate a java {@link ExecutorService} thread pool that starts with the specified minimum number of
+ * threads and then scales up to the specified max number of threads as needed for excess work, scaling back when the burst of activity
+ * stops. As opposed to the {@link FixedExecutorBuilder} that keeps a fixed number of threads alive.
  */
 public final class ScalingExecutorBuilder extends ExecutorBuilder<ScalingExecutorBuilder.ScalingExecutorSettings> {
 

server/src/main/java/org/elasticsearch/threadpool/ThreadPool.java

@@ -60,12 +60,28 @@
 import static java.util.Map.entry;
 import static org.elasticsearch.core.Strings.format;
 
+/**
+ * Manages all the Java thread pools we create. {@link Names} contains a list of the thread pools, but plugins can dynamically add more
+ * thread pools to instantiate.
+ */
 public class ThreadPool implements ReportingService<ThreadPoolInfo>, Scheduler {
 
     private static final Logger logger = LogManager.getLogger(ThreadPool.class);
 
+    /**
+     * List of names that identify Java thread pools that are created in {@link ThreadPool#ThreadPool}.
+     */
     public static class Names {
+        /**
+         * All the tasks that do not relate to the purpose of one of the other thread pools should use this thread pool. Try to pick one of
+         * the other more specific thread pools where possible.
+         */
         public static final String GENERIC = "generic";
+        /**
+         * Important management tasks that keep the cluster from falling apart.
+         * This thread pool ensures cluster coordination tasks do not get blocked by less critical tasks and can continue to make progress.
+         * This thread pool also defaults to a single thread, reducing contention on the Coordinator mutex.
+         */
         public static final String CLUSTER_COORDINATION = "cluster_coordination";
         public static final String GET = "get";
         public static final String ANALYZE = "analyze";
@@ -75,6 +91,10 @@ public static class Names {
         public static final String SEARCH_COORDINATION = "search_coordination";
         public static final String AUTO_COMPLETE = "auto_complete";
         public static final String SEARCH_THROTTLED = "search_throttled";
+        /**
+         * Cluster management tasks. Tasks that manage data, and tasks that report on cluster health via statistics etc.
+         * Not a latency sensitive thread pool: some tasks may time be long-running; and the thread pool size is limited / relatively small.
+         */
         public static final String MANAGEMENT = "management";
         public static final String FLUSH = "flush";
         public static final String REFRESH = "refresh";
@@ -199,6 +219,13 @@ public Collection<ExecutorBuilder> builders() {
         Setting.Property.NodeScope
     );
 
+    /**
+     * Defines and builds the many thread pools delineated in {@link Names}.
+     *
+     * @param settings
+     * @param meterRegistry
+     * @param customBuilders a list of additional thread pool builders that were defined elsewhere (like a Plugin).
+     */
     @SuppressWarnings({ "rawtypes", "unchecked" })
     public ThreadPool(final Settings settings, MeterRegistry meterRegistry, final ExecutorBuilder<?>... customBuilders) {
         assert Node.NODE_NAME_SETTING.exists(settings);
@@ -327,6 +354,7 @@ public ThreadPool(final Settings settings, MeterRegistry meterRegistry, final Ex
 
         threadContext = new ThreadContext(settings);
 
+        // Now that all the thread pools have been defined, actually build them.
         final Map<String, ExecutorHolder> executors = new HashMap<>();
         for (final Map.Entry<String, ExecutorBuilder> entry : builders.entrySet()) {
             final ExecutorBuilder.ExecutorSettings executorSettings = entry.getValue().getSettings(settings);
@@ -902,6 +930,11 @@ void check(long newAbsoluteMillis, long newRelativeNanos) {
         }
     }
 
+    /**
+     * Holds a thread pool and additional ES information ({@link Info}) about that Java thread pool ({@link ExecutorService}) instance.
+     *
+     * See {@link Names} for a list of thread pools, though there can be more dynamically added via plugins.
+     */
     static class ExecutorHolder {
         private final ExecutorService executor;
         public final Info info;
@@ -917,6 +950,9 @@ ExecutorService executor() {
         }
     }
 
+    /**
+     * The settings used to create a Java ExecutorService thread pool.
+     */
     public static class Info implements Writeable, ToXContentFragment {
 
         private final String name;

server/src/test/java/org/elasticsearch/repositories/blobstore/BlobStoreRepositoryRestoreTests.java

@@ -227,7 +227,7 @@ private Repository createRepository() {
             new RecoverySettings(Settings.EMPTY, new ClusterSettings(Settings.EMPTY, ClusterSettings.BUILT_IN_CLUSTER_SETTINGS))
         ) {
             @Override
-            protected void assertSnapshotOrGenericThread() {
+            protected void assertSnapshotOrStatelessPermittedThreadPool() {
                 // eliminate thread name check as we create repo manually
             }
         };

server/src/test/java/org/elasticsearch/snapshots/SnapshotResiliencyTests.java

@@ -2130,7 +2130,7 @@ public RecyclerBytesStreamOutput newNetworkBytesStream() {
                             recoverySettings
                         ) {
                             @Override
-                            protected void assertSnapshotOrGenericThread() {
+                            protected void assertSnapshotOrStatelessPermittedThreadPool() {
                                 // eliminate thread name check as we create repo in the test thread
                             }
                         }

x-pack/plugin/searchable-snapshots/src/internalClusterTest/java/org/elasticsearch/xpack/searchablesnapshots/cache/full/SearchableSnapshotsPrewarmingIntegTests.java

@@ -449,9 +449,9 @@ public Map<String, Repository.Factory> getRepositories(
                 (metadata) -> new FsRepository(metadata, env, namedXContentRegistry, clusterService, bigArrays, recoverySettings) {
 
                     @Override
-                    protected void assertSnapshotOrGenericThread() {
+                    protected void assertSnapshotOrStatelessPermittedThreadPool() {
                         if (enabled.get()) {
-                            super.assertSnapshotOrGenericThread();
+                            super.assertSnapshotOrStatelessPermittedThreadPool();
                         }
                     }
 

x-pack/plugin/searchable-snapshots/src/internalClusterTest/java/org/elasticsearch/xpack/searchablesnapshots/recovery/SearchableSnapshotRecoveryStateIntegrationTests.java

@@ -248,7 +248,7 @@ public Map<String, Repository.Factory> getRepositories(
                 "test-fs",
                 (metadata) -> new FsRepository(metadata, env, namedXContentRegistry, clusterService, bigArrays, recoverySettings) {
                     @Override
-                    protected void assertSnapshotOrGenericThread() {
+                    protected void assertSnapshotOrStatelessPermittedThreadPool() {
                         // ignore
                     }
                 }

x-pack/plugin/searchable-snapshots/src/test/java/org/elasticsearch/xpack/searchablesnapshots/store/SearchableSnapshotDirectoryTests.java

@@ -609,7 +609,7 @@ private void testDirectories(
                 ) {
 
                     @Override
-                    protected void assertSnapshotOrGenericThread() {
+                    protected void assertSnapshotOrStatelessPermittedThreadPool() {
                         // eliminate thread name check as we create repo manually on test/main threads
                     }
                 };