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 index 3ba1bf563ef..a4d4564a46d 100644 --- 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. * *
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 index 92040d9bc58..cf7cc258961 100644 --- 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. + * + *
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. + * + *
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