api: Better explain the executors and how to configure them

Author: ejona86

api/src/main/java/io/grpc/ClientInterceptor.java

@@ -32,6 +32,11 @@
  * CallCredentials}. But a {@code ClientInterceptor} could set the {@code
  * CallCredentials} within the {@link CallOptions}.
  *
+ * <p>From gRPC's perspective, interceptors don't generally exist and are more of a convenience.
+ * Convenience APIs will use {@link ClientInterceptors} to convert the interceptor into a {@code
+ * Channel}. Thus interceptors are an extension of the application and run on the same
+ * threads and receive callbacks using the same executor.
+ *
  * <p>The interceptor may be called for multiple {@link ClientCall calls} by one or more threads
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ClientCall.Listener ClientCall.Listener} docs for more details regarding thread

api/src/main/java/io/grpc/ManagedChannelBuilder.java

@@ -92,12 +92,13 @@ public static ManagedChannelBuilder<?> forTarget(String target) {
   }
 
   /**
-   * Execute application code directly in the transport thread.
-   *
-   * <p>Depending on the underlying transport, using a direct executor may lead to substantial
-   * performance improvements. However, it also requires the application to not block under
+   * Execute application code directly in the transport thread. The application must not block under
    * any circumstances.
    *
+   * <p>Depending on the underlying transport and the application code, using a direct executor may
+   * lead to 10s of µs latency reduction but causes a substantial performance degradation when
+   * misused.
+   *
    * <p>Calling this method is semantically equivalent to calling {@link #executor(Executor)} and
    * passing in a direct executor. However, this is the preferred way as it may allow the transport
    * to perform special optimizations.
@@ -108,7 +109,10 @@ public static ManagedChannelBuilder<?> forTarget(String target) {
   public abstract T directExecutor();
 
   /**
-   * Provides a custom executor.
+   * Set the default executor for callbacks. This is used for async and future stub callbacks, but
+   * can be overridden by {@link CallOptions#withExecutor} and {@code stub.withExecutor()}. Blocking
+   * stubs specify a per-RPC executor. This is also used for {@link
+   * ManagedChannel#notifyWhenStateChanged}.
    *
    * <p>It's an optional parameter. If the user has not provided an executor when the channel is
    * built, the builder will use a static cached thread pool.

api/src/main/java/io/grpc/ServerBuilder.java

@@ -45,12 +45,13 @@ public static ServerBuilder<?> forPort(int port) {
   }
 
   /**
-   * Execute application code directly in the transport thread.
-   *
-   * <p>Depending on the underlying transport, using a direct executor may lead to substantial
-   * performance improvements. However, it also requires the application to not block under
+   * Execute application code directly in the transport thread. The application must not block under
    * any circumstances.
    *
+   * <p>Depending on the underlying transport and the application code, using a direct executor may
+   * lead to 10s of µs latency reduction but causes a substantial performance degradation when
+   * misused.
+   *
    * <p>Calling this method is semantically equivalent to calling {@link #executor(Executor)} and
    * passing in a direct executor. However, this is the preferred way as it may allow the transport
    * to perform special optimizations.
@@ -61,10 +62,11 @@ public static ServerBuilder<?> forPort(int port) {
   public abstract T directExecutor();
 
   /**
-   * Provides a custom executor.
+   * Set the default executor for service callbacks.
    *
    * <p>It's an optional parameter. If the user has not provided an executor when the server is
-   * built, the builder will use a static cached thread pool.
+   * built, the builder will use a static cached thread pool. Users are encouraged to specify their
+   * own executor that limits the number of threads.
    *
    * <p>The server won't take ownership of the given executor. It's caller's responsibility to
    * shut down the executor when it's desired.
@@ -85,11 +87,13 @@ public static ServerBuilder<?> forPort(int port) {
    * it switches over. But if calling {@link ServerCallExecutorSupplier} returns null, the server
    * call is still handled by the default {@link #executor(Executor)} as a fallback.
    *
+   * <p>If your {@code executorSupplier} runs quickly and always returns a non-{@code null}
+   * executor, then you may want to use {@link #directExecutor} to reduce latency.
+   *
    * @param executorSupplier the server call executor provider
    * @return this
    * @since 1.39.0
-   *
-   * */
+   */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/8274")
   public T callExecutor(ServerCallExecutorSupplier executorSupplier) {
     return thisT();

api/src/main/java/io/grpc/ServerInterceptor.java

@@ -29,6 +29,11 @@
  * <li>Delegating calls to other servers</li>
  * </ul>
  *
+ * <p>From gRPC's perspective, interceptors don't generally exist and are more of a convenience.
+ * Convenience APIs will use {@link ServerInterceptors} to convert the interceptor into a {@code
+ * ServerCallHandler}. Thus interceptors are an extension of the application and run on the same
+ * threads and receive callbacks using the same executor.
+ *
  * <p>The interceptor may be called for multiple {@link ServerCall calls} by one or more threads
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ServerCall.Listener ServerCall.Listener} docs for more details regarding thread