grpc
/
grpc-java
mirror of https://github.com/grpc/grpc-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Eric Anderson 2020-07-01 13:58:53 -05:00 committed by GitHub
parent f5b976dd5c
commit 21269bd188
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
View File

@ -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}.