[API] Document gotcha in AsyncNotifyWhenDone behavior (#33208)

As the [issue](https://github.com/grpc/grpc/issues/10136) documents, the
behavior of AsyncNotifyWhenDone is documented as:

"The comment on `AsyncNotifyWhenDone` states "Has to be called before
the rpc starts" but it seems that if the request tag is returned with
ok=false (i.e. because the CQ is shutting down) then the async done tag
is never received. Instead, I expect the async done tag to be received
regardless of whether or not an incoming call request was successfully
received."

The TODO item is marked closed as stale, and it seems unlikely this will
be resolved, without breaking
existing users whose code is written under the assumption that the tag
is not seen if the call never starts, so it may be time to documented
the idiosyncratic corner case and make it the expected behavior.
pull/33232/head
Mehrdad Afshari 2 years ago committed by GitHub
parent 0d3ecd3e63
commit 20023faa2e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 4
      include/grpcpp/server_context.h

@ -305,8 +305,8 @@ class ServerContextBase {
/// Async only. Has to be called before the rpc starts.
/// Returns the tag in completion queue when the rpc finishes.
/// IsCancelled() can then be called to check whether the rpc was cancelled.
/// TODO(vjpai): Fix this so that the tag is returned even if the call never
/// starts (https://github.com/grpc/grpc/issues/10136).
/// Note: the tag will only be returned if call starts.
/// If the call never starts, this tag will not be returned.
void AsyncNotifyWhenDone(void* tag) {
has_notify_when_done_tag_ = true;
async_notify_when_done_tag_ = tag;

Loading…
Cancel
Save