stub: Improve threading expectation docs

This mainly copies documentation from other places, like StreamObserver
and ClientCall, but does fix some missing important threading notes.

Fixes #3413

4 files changed, 23 insertions, 2 deletions

diff --git a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
index ab01cf255..f9845700e 100644
--- a/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/CallStreamObserver.java
@@ -35,6 +35,8 @@ import io.grpc.ExperimentalApi;
  *
  * <p>Implementations of this class represent the 'outbound' message stream.
  *
+ * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple
+ * threads will be writing to an instance concurrently, the application must synchronize its calls.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1788")
 @DoNotMock
@@ -54,6 +56,10 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    * thread will always be used to execute the {@link Runnable}, it is guaranteed that executions
    * are serialized with calls to the 'inbound' {@link StreamObserver}.
    *
+   * <p>On client-side this method may only be called during {@link
+   * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial
+   * call to the application, before the service returns its {@code StreamObserver}.
+   *
    * <p>Note that the handler may be called some time after {@link #isReady} has transitioned to
    * true as other callbacks may still be executing in the 'inbound' observer.
    *
@@ -66,6 +72,10 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    * to the 'inbound' {@link io.grpc.stub.StreamObserver#onNext(Object)} has completed. If disabled
    * an application must make explicit calls to {@link #request} to receive messages.
    *
+   * <p>On client-side this method may only be called during {@link
+   * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial
+   * call to the application, before the service returns its {@code StreamObserver}.
+   *
    * <p>Note that for cases where the runtime knows that only one inbound message is allowed
    * calling this method will have no effect and the runtime will always permit one and only
    * one message. This is true for:
@@ -85,6 +95,9 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
   /**
    * Requests the peer to produce {@code count} more messages to be delivered to the 'inbound'
    * {@link StreamObserver}.
+   *
+   * <p>This method is safe to call from multiple threads without external synchronization.
+   *
    * @param count more messages
    */
   public abstract void request(int count);
diff --git a/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
index 8a2509908..bb26053b5 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
@@ -24,6 +24,9 @@ import javax.annotation.Nullable;
 /**
  * A refinement of {@link CallStreamObserver} that allows for lower-level interaction with
  * client calls.
+ *
+ * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple
+ * threads will be writing to an instance concurrently, the application must synchronize its calls.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1788")
 @DoNotMock
diff --git a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
index 0f5c3d375..5c144192b 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
@@ -22,6 +22,9 @@ import io.grpc.ExperimentalApi;
 /**
  * A refinement of {@link CallStreamObserver} to allows for interaction with call
  * cancellation events on the server side.
+ *
+ * <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple
+ * threads will be writing to an instance concurrently, the application must synchronize its calls.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1788")
 @DoNotMock
@@ -29,6 +32,8 @@ public abstract class ServerCallStreamObserver<V> extends CallStreamObserver<V>
 
   /**
    * If {@code true} indicates that the call has been cancelled by the remote peer.
+   *
+   * <p>This method may safely be called concurrently from multiple threads.
    */
   public abstract boolean isCancelled();
 
diff --git a/stub/src/main/java/io/grpc/stub/StreamObserver.java b/stub/src/main/java/io/grpc/stub/StreamObserver.java
index 4cc64f028..f4ed809a1 100644
--- a/stub/src/main/java/io/grpc/stub/StreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/StreamObserver.java
@@ -25,8 +25,8 @@ package io.grpc.stub;
  * library to the application. For incoming messages, the application implements the
  * {@code StreamObserver} and passes it to the GRPC library for receiving.
  *
- * <p>Implementations are expected to be
- * <a href="http://www.ibm.com/developerworks/library/j-jtp09263/">thread-compatible</a>.
+ * <p>Implementations are not required to be thread-safe (but should be
+ * <a href="http://www.ibm.com/developerworks/library/j-jtp09263/">thread-compatible</a>).
  * Separate {@code StreamObserver}s do
  * not need to be synchronized together; incoming and outgoing directions are independent.
  * Since individual {@code StreamObserver}s are not thread-safe, if multiple threads will be