From 8918aaeccd4cd22cc6e549dcb3ddc0d661993e97 Mon Sep 17 00:00:00 2001 From: Craig Tiller <ctiller@google.com> Date: Mon, 6 Mar 2017 15:59:08 -0800 Subject: [PATCH] Document status ordering rules This documents a rule that's existed in a hard to find internal document that's existed since Feb 2016 by abhikumar@google.com. Since that rule is critical to untangling some gRPC C core behavior, we should document it publically. --- doc/status_ordering.md | 16 ++++++++++++++++ .../end2end/tests/streaming_error_response.c | 3 +++ 2 files changed, 19 insertions(+) create mode 100644 doc/status_ordering.md diff --git a/doc/status_ordering.md b/doc/status_ordering.md new file mode 100644 index 0000000000..fccfa863a3 --- /dev/null +++ b/doc/status_ordering.md @@ -0,0 +1,16 @@ +Ordering Status and Reads in the gRPC API +----------------------------------------- + +Rules for implementors: +1. Reads and Writes Must not succeed after Status has been delivered. +2. OK Status is only delivered after all buffered messages are read. +3. Reads May continue to succeed after a failing write. + However, once a write fails, all subsequent writes Must fail, + and similarly, once a read fails, all subsequent reads Must fail. +4. When an error status is known to the library, if the user asks for status, + the library Should discard messages received in the library but not delivered + to the user and then deliver the status. If the user does not ask for status + but continues reading, the library Should deliver buffered messages before + delivering status. The library MAY choose to implement the stricter version + where errors cause all buffered messages to be dropped, but this is not a + requirement. diff --git a/test/core/end2end/tests/streaming_error_response.c b/test/core/end2end/tests/streaming_error_response.c index 42055907c8..2b9c404b15 100644 --- a/test/core/end2end/tests/streaming_error_response.c +++ b/test/core/end2end/tests/streaming_error_response.c @@ -31,6 +31,9 @@ * */ +/** \file Verify that status ordering rules are obeyed. + \ref doc/status_ordering.md */ + #include "test/core/end2end/end2end_tests.h" #include <stdio.h> -- GitLab