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. + * *
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 diff --git a/api/src/main/java/io/grpc/ManagedChannelBuilder.java b/api/src/main/java/io/grpc/ManagedChannelBuilder.java index e129e7ad14f..d7cc623c119 100644 --- a/api/src/main/java/io/grpc/ManagedChannelBuilder.java +++ b/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. - * - *
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. * + *
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. + * *
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}. * *
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. diff --git a/api/src/main/java/io/grpc/ServerBuilder.java b/api/src/main/java/io/grpc/ServerBuilder.java index 3effe593e57..73521cd117d 100644 --- a/api/src/main/java/io/grpc/ServerBuilder.java +++ b/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. - * - *
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. * + *
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. + * *
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. * *
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. * *
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. * + *
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(); diff --git a/api/src/main/java/io/grpc/ServerInterceptor.java b/api/src/main/java/io/grpc/ServerInterceptor.java index 2944cf680fe..ddb8ea8cc02 100644 --- a/api/src/main/java/io/grpc/ServerInterceptor.java +++ b/api/src/main/java/io/grpc/ServerInterceptor.java @@ -29,6 +29,11 @@ *
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. + * *
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