stub: Document StreamObserver is an async API

ejona86 · web-flow · commit 5cc94a548870 · 2021-08-30T11:15:05.000-07:00
Missing docs were brought up in grpc#8423
diff --git a/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ClientCallStreamObserver.java
@@ -20,7 +20,8 @@
 
 /**
  * A refinement of {@link CallStreamObserver} that allows for lower-level interaction with
- * client calls.
+ * client calls. An instance of this class is obtained via {@link ClientResponseObserver}, or by
+ * manually casting the {@code StreamObserver} returned by a stub.
  *
  * <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.
diff --git a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
@@ -18,7 +18,8 @@
 
 /**
  * A refinement of {@link CallStreamObserver} to allows for interaction with call
- * cancellation events on the server side.
+ * cancellation events on the server side. An instance of this class is obtained by casting the
+ * {@code StreamObserver} passed as an argument to service implementations.
  *
  * <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.
diff --git a/stub/src/main/java/io/grpc/stub/StreamObserver.java b/stub/src/main/java/io/grpc/stub/StreamObserver.java
@@ -31,6 +31,16 @@
  * 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
  * writing to a {@code StreamObserver} concurrently, the application must synchronize calls.
+ *
+ * <p>This API is asynchronous, so methods may return before the operation completes. The API
+ * provides no guarantees for how quickly an operation will complete, so utilizing flow control via
+ * {@link ClientCallStreamObserver} and {@link ServerCallStreamObserver} to avoid excessive
+ * buffering is recommended for streaming RPCs. gRPC's implementation of {@code onError()} on
+ * client-side causes the RPC to be cancelled and discards all messages, so completes quickly.
+ *
+ * <p>gRPC guarantees it does not block on I/O in its implementation, but applications are allowed
+ * to perform blocking operations in their implementations. However, doing so will delay other
+ * callbacks because the methods cannot be called concurrently.
  */
 public interface StreamObserver<V>  {
   /**

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,8 @@`
`20`	`20`
`21`	`21`	`/**`
`22`	`22`	`* A refinement of {@link CallStreamObserver} that allows for lower-level interaction with`
`23`		`- * client calls.`
	`23`	`+ * client calls. An instance of this class is obtained via {@link ClientResponseObserver}, or by`
	`24`	`+ * manually casting the {@code StreamObserver} returned by a stub.`
`24`	`25`	`*`
`25`	`26`	`* <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple`
`26`	`27`	`* threads will be writing to an instance concurrently, the application must synchronize its calls.`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,8 @@`
`18`	`18`
`19`	`19`	`/**`
`20`	`20`	`* A refinement of {@link CallStreamObserver} to allows for interaction with call`
`21`		`- * cancellation events on the server side.`
	`21`	`+ * cancellation events on the server side. An instance of this class is obtained by casting the`
	`22`	`+ * {@code StreamObserver} passed as an argument to service implementations.`
`22`	`23`	`*`
`23`	`24`	`* <p>Like {@code StreamObserver}, implementations are not required to be thread-safe; if multiple`
`24`	`25`	`* threads will be writing to an instance concurrently, the application must synchronize its calls.`