From 21269bd18864ee420678cf43891d93c553ebd9b8 Mon Sep 17 00:00:00 2001
From: Eric Anderson <ejona@google.com>
Date: Wed, 1 Jul 2020 13:58:53 -0500
Subject: [PATCH] stub: Clarify ServerCallStreamObserver cancellation

This avoids the "changes" description, which could be understood to mean that
the transition is important instead of the steady-state and thus a callback
might not be called (which is not the case).

Much of the language was copied from ServerCall.
---
 .../grpc/stub/ServerCallStreamObserver.java   | 21 +++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
index 9190aa580e..7a538b0e5d 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
@@ -32,19 +32,28 @@ import io.grpc.ExperimentalApi;
 public abstract class ServerCallStreamObserver<V> extends CallStreamObserver<V> {
 
   /**
-   * If {@code true} indicates that the call has been cancelled by the remote peer.
+   * Returns {@code true} when the call is cancelled and the server is encouraged to abort
+   * processing to save resources, since the client will not be processing any further methods.
+   * Cancellations can be caused by timeouts, explicit cancellation by client, network errors, and
+   * similar.
    *
    * <p>This method may safely be called concurrently from multiple threads.
    */
   public abstract boolean isCancelled();
 
   /**
-   * Set a {@link Runnable} that will be called if the calls {@link #isCancelled()} state
-   * changes from {@code false} to {@code true}. It is guaranteed that execution of the
-   * {@link Runnable} are serialized with calls to the 'inbound' {@link StreamObserver}.
+   * Sets a {@link Runnable} to be called if the call is cancelled and the server is encouraged to
+   * abort processing to save resources, since the client will not process any further messages.
+   * Cancellations can be caused by timeouts, explicit cancellation by the client, network errors,
+   * etc.
    *
-   * <p>Note that the handler may be called some time after {@link #isCancelled()} has transitioned
-   * to {@code true} as other callbacks may still be executing in the 'inbound' observer.
+   * <p>It is guaranteed that execution of the {@link Runnable} is serialized with calls to the
+   * 'inbound' {@link StreamObserver}. That also means that the callback will be delayed if other
+   * callbacks are running; if one of those other callbacks runs for a significant amount of time
+   * it can poll {@link #isCancelled()}, which is not delayed.
+   *
+   * <p>This method may only be called during the initial call to the application, before the
+   * service returns its {@code StreamObserver}.
    *
    * <p>Setting the onCancelHandler will suppress the on-cancel exception thrown by
    * {@link #onNext}.