Add implementation note regarding server interceptors and thread locals

grpc · Oct 13, 2020 · b735505 · b735505
1 parent b08ce41
commit b735505
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 2 deletions.
diff --git a/api/src/main/java/io/grpc/ClientCall.java b/api/src/main/java/io/grpc/ClientCall.java
@@ -104,7 +104,10 @@ public abstract class ClientCall<ReqT, RespT> {
    * Callbacks for receiving metadata, response messages and completion status from the server.
    *
    * <p>Implementations are free to block for extended periods of time. Implementations are not
-   * required to be thread-safe.
+   * required to be thread-safe, but they must not be thread-hostile. The caller is free to call
+   * an instance from multiple threads, but only one call simultaneously. A single thread may
+   * interleave calls to multiple instances, so implementations using ThreadLocals must be careful
+   * to avoid leaking inappropriate state (e.g., clearing the ThreadLocal before returning).
    */
   public abstract static class Listener<T> {
 

diff --git a/api/src/main/java/io/grpc/ClientInterceptor.java b/api/src/main/java/io/grpc/ClientInterceptor.java
@@ -32,6 +32,11 @@
  * <p>Providing authentication credentials is better served by {@link
  * CallCredentials}. But a {@code ClientInterceptor} could set the {@code
  * CallCredentials} within the {@link CallOptions}.
+ *
+ * <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
+ * safety of the returned listener.
  */
 @ThreadSafe
 public interface ClientInterceptor {

diff --git a/api/src/main/java/io/grpc/ServerCall.java b/api/src/main/java/io/grpc/ServerCall.java
@@ -46,7 +46,10 @@ public abstract class ServerCall<ReqT, RespT> {
    * close, which is guaranteed before completion.
    *
    * <p>Implementations are free to block for extended periods of time. Implementations are not
-   * required to be thread-safe.
+   * required to be thread-safe, but they must not be thread-hostile. The caller is free to call
+   * an instance from multiple threads, but only one call simultaneously. A single thread may
+   * interleave calls to multiple instances, so implementations using ThreadLocals must be careful
+   * to avoid leaking inappropriate state (e.g., clearing the ThreadLocal before returning).
    */
   // TODO(ejona86): We need to decide what to do in the case of server closing with non-cancellation
   // before client half closes. It may be that we treat such a case as an error. If we permit such

diff --git a/api/src/main/java/io/grpc/ServerInterceptor.java b/api/src/main/java/io/grpc/ServerInterceptor.java
@@ -29,6 +29,11 @@
  * <li>Logging and monitoring call behavior</li>
  * <li>Delegating calls to other servers</li>
  * </ul>
+ *
+ * <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
+ * safety of the returned listener.
  */
 @ThreadSafe
 public interface ServerInterceptor {