From cf88bb4aa55fda6705471579768f6c5f941cef26 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Wed, 10 Aug 2016 12:36:01 -0700 Subject: [PATCH] Rename Fail Fast doc to Wait for Ready The intention is to deminish the term "fail fast" and instead encourage "wait for ready." However, the semantics of "the opposite of fail fast" weren't really documented since that was the previous default, so it became a bit of a rewrite to define both terms. The file name uses dashes instead of underscore, since dashes are more common in the docs. --- doc/fail_fast.md | 16 +--------------- doc/wait-for-ready.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 15 deletions(-) create mode 100644 doc/wait-for-ready.md diff --git a/doc/fail_fast.md b/doc/fail_fast.md index 3ed4297194b..2dd5561fc67 100644 --- a/doc/fail_fast.md +++ b/doc/fail_fast.md @@ -1,15 +1 @@ -gRPC Fail Fast Semantics -======================== - -Fail fast requests allow terminating requests (with status UNAVAILABLE) prior -to the deadline of the request being met. - -gRPC implementations of fail fast can terminate requests whenever a channel is -in the TRANSIENT_FAILURE or SHUTDOWN states. If the channel is in any other -state (CONNECTING, READY, or IDLE) the request should not be terminated. - -Fail fast SHOULD be the default for gRPC implementations, with an option to -switch to non fail fast. - -The opposite of fail fast is 'ignore connectivity'. - +Moved to wait-for-ready.md diff --git a/doc/wait-for-ready.md b/doc/wait-for-ready.md new file mode 100644 index 00000000000..fd426042693 --- /dev/null +++ b/doc/wait-for-ready.md @@ -0,0 +1,14 @@ +gRPC Wait for Ready Semantics +============================= + +If an RPC is issued but the channel is in `TRANSIENT_FAILURE` or `SHUTDOWN` +states, the RPC is unable to be transmited promptly. By default, gRPC +implementations SHOULD fail such RPCs immediately. This is known as "fail fast," +but usage of the term is historical. RPCs SHOULD NOT fail as a result of the +channel being in other states (`CONNECTING`, `READY`, or `IDLE`). + +gRPC implementations MAY provide a per-RPC option to not fail RPCs as a result +of the channel being in `TRANSIENT_FAILURE` state. Instead, the implementation +queues the RPCs until the channel is `READY`. This is known as "wait for ready." +The RPCs SHOULD still fail before `READY` if there are unrelated reasons, such +as the channel is `SHUTDOWN` or the RPC's deadline is reached.