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

api,stub: Clarify isReady()/onReady() interaction semantics

This commit is contained in:
Eric Anderson 2019-05-28 17:52:39 -07:00
parent ad0893737e
commit bc2e1764f6
3 changed files with 32 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
api/src/main/java/io/grpc/ClientCall.java
View File

@ -144,11 +144,17 @@ public abstract class ClientCall<ReqT, RespT> {
public void onClose(Status status, Metadata trailers) {}
/**
* This indicates that the ClientCall is now capable of sending additional messages (via
* This indicates that the ClientCall may now be capable of sending additional messages (via
* {@link #sendMessage}) without requiring excessive buffering internally. This event is
* just a suggestion and the application is free to ignore it, however doing so may
* result in excessive buffering within the ClientCall.
*
* <p>Because there is a processing delay to deliver this notification, it is possible for
* concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
* notifications by checking {@code isReady()}'s current value instead of assuming it is now
* {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
* <em>another</em> {@code onReady()} callback.
*
* <p>If the type of a call is either {@link MethodDescriptor.MethodType#UNARY} or
* {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this callback may not be fired. Calls
* that send exactly one message should not await this callback.
@ -236,12 +242,15 @@ public abstract class ClientCall<ReqT, RespT> {
* just a suggestion and the application is free to ignore it, however doing so may
* result in excessive buffering within the call.
*
* <p>This abstract class's implementation always returns {@code true}. Implementations generally
* override the method.
* <p>If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()}
* transitions to {@code true}.
*
* <p>If the type of the call is either {@link MethodDescriptor.MethodType#UNARY} or
* {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this method may persistently return
* false. Calls that send exactly one message should not check this method.
*
* <p>This abstract class's implementation always returns {@code true}. Implementations generally
* override the method.
*/
public boolean isReady() {
return true;

14
api/src/main/java/io/grpc/ServerCall.java
View File

@ -83,10 +83,16 @@ public abstract class ServerCall<ReqT, RespT> {
public void onComplete() {}
/**
* This indicates that the call is now capable of sending additional messages (via
* This indicates that the call may now be capable of sending additional messages (via
* {@link #sendMessage}) without requiring excessive buffering internally. This event is
* just a suggestion and the application is free to ignore it, however doing so may
* result in excessive buffering within the call.
*
* <p>Because there is a processing delay to deliver this notification, it is possible for
* concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
* notifications by checking {@code isReady()}'s current value instead of assuming it is now
* {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
* <em>another</em> {@code onReady()} callback.
*/
public void onReady() {}
}
@ -133,7 +139,11 @@ public abstract class ServerCall<ReqT, RespT> {
* just a suggestion and the application is free to ignore it, however doing so may
* result in excessive buffering within the call.
*
* <p>This implementation always returns {@code true}.
* <p>If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()}
* transitions to {@code true}.
*
* <p>This abstract class's implementation always returns {@code true}. Implementations generally
* override the method.
*/
public boolean isReady() {
return true;

10
stub/src/main/java/io/grpc/stub/CallStreamObserver.java
View File

@ -48,6 +48,9 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
* without requiring excessive buffering internally. This value is just a suggestion and the
* application is free to ignore it, however doing so may result in excessive buffering within the
* observer.
*
* <p>If {@code false}, the runnable passed to {@link #setOnReadyHandler} will be called after
* {@code isReady()} transitions to {@code true}.
*/
public abstract boolean isReady();
@ -61,8 +64,11 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
* 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.
* <p>Because there is a processing delay to deliver this notification, it is possible for
* concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
* notifications by checking {@code isReady()}'s current value instead of assuming it is now
* {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
* <em>another</em> {@code onReadyHandler} callback.
*
* @param onReadyHandler to call when peer is ready to receive more messages.
*/