From c1df38f2b97369b4cbbdf697331e61eea06059a9 Mon Sep 17 00:00:00 2001 From: Lidi Zheng Date: Wed, 22 Apr 2020 13:38:22 -0700 Subject: [PATCH 1/2] Document wait_for_ready mechanism in Python's glossary --- doc/python/sphinx/glossary.rst | 14 +++++++++++++ src/python/grpcio/grpc/__init__.py | 20 +++++++++---------- .../grpc/experimental/aio/_base_channel.py | 8 ++++---- .../grpc/experimental/aio/_interceptor.py | 4 ++-- 4 files changed, 30 insertions(+), 16 deletions(-) diff --git a/doc/python/sphinx/glossary.rst b/doc/python/sphinx/glossary.rst index cae5f4a32e3..353c5a3c11b 100644 --- a/doc/python/sphinx/glossary.rst +++ b/doc/python/sphinx/glossary.rst @@ -27,3 +27,17 @@ Glossary the returned object doesn't have restrictions (i.e. ``None`` allowed). The deserializer is invoked with inbound message bytes on both the server side and the client-side. + + wait_for_ready + If an RPC is issued but the channel is in TRANSIENT_FAILURE or SHUTDOWN + states, the RPC is unable to be transmitted promptly. By default, gRPC + implementations SHOULD fail such RPCs immediately. This is known as "fail + fast," but the 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. diff --git a/src/python/grpcio/grpc/__init__.py b/src/python/grpcio/grpc/__init__.py index ff799cd07e9..75b1a923f67 100644 --- a/src/python/grpcio/grpc/__init__.py +++ b/src/python/grpcio/grpc/__init__.py @@ -414,8 +414,8 @@ class ClientCallDetails(six.with_metaclass(abc.ABCMeta)): metadata: Optional :term:`metadata` to be transmitted to the service-side of the RPC. credentials: An optional CallCredentials for the RPC. - wait_for_ready: This is an EXPERIMENTAL argument. An optional flag t - enable wait for ready mechanism. + wait_for_ready: This is an EXPERIMENTAL argument. An optional + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. """ @@ -690,7 +690,7 @@ class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -723,7 +723,7 @@ class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -756,7 +756,7 @@ class UnaryUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -792,7 +792,7 @@ class UnaryStreamMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -828,7 +828,7 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -862,7 +862,7 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -895,7 +895,7 @@ class StreamUnaryMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -931,7 +931,7 @@ class StreamStreamMultiCallable(six.with_metaclass(abc.ABCMeta)): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. diff --git a/src/python/grpcio/grpc/experimental/aio/_base_channel.py b/src/python/grpcio/grpc/experimental/aio/_base_channel.py index b6c946a4367..33efa7789cb 100644 --- a/src/python/grpcio/grpc/experimental/aio/_base_channel.py +++ b/src/python/grpcio/grpc/experimental/aio/_base_channel.py @@ -49,7 +49,7 @@ class UnaryUnaryMultiCallable(abc.ABC): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -87,7 +87,7 @@ class UnaryStreamMultiCallable(abc.ABC): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -125,7 +125,7 @@ class StreamUnaryMultiCallable(abc.ABC): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. @@ -163,7 +163,7 @@ class StreamStreamMultiCallable(abc.ABC): credentials: An optional CallCredentials for the RPC. Only valid for secure Channel. wait_for_ready: This is an EXPERIMENTAL argument. An optional - flag to enable wait for ready mechanism + flag to enable :term:`wait_for_ready` mechanism. compression: An element of grpc.compression, e.g. grpc.compression.Gzip. This is an EXPERIMENTAL option. diff --git a/src/python/grpcio/grpc/experimental/aio/_interceptor.py b/src/python/grpcio/grpc/experimental/aio/_interceptor.py index d4aca3ae0fc..f47f2927f02 100644 --- a/src/python/grpcio/grpc/experimental/aio/_interceptor.py +++ b/src/python/grpcio/grpc/experimental/aio/_interceptor.py @@ -73,8 +73,8 @@ class ClientCallDetails( metadata: Optional metadata to be transmitted to the service-side of the RPC. credentials: An optional CallCredentials for the RPC. - wait_for_ready: This is an EXPERIMENTAL argument. An optional flag to - enable wait for ready mechanism. + wait_for_ready: This is an EXPERIMENTAL argument. An optional + flag to enable :term:`wait_for_ready` mechanism. """ method: str From f7d71ccfa6f4d0058a0e2e7163b1f4c64f54f69f Mon Sep 17 00:00:00 2001 From: Lidi Zheng Date: Wed, 22 Apr 2020 14:51:21 -0700 Subject: [PATCH 2/2] Update the glossary --- doc/python/sphinx/glossary.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/doc/python/sphinx/glossary.rst b/doc/python/sphinx/glossary.rst index 353c5a3c11b..fb44bdf114d 100644 --- a/doc/python/sphinx/glossary.rst +++ b/doc/python/sphinx/glossary.rst @@ -29,15 +29,13 @@ Glossary and the client-side. wait_for_ready - If an RPC is issued but the channel is in TRANSIENT_FAILURE or SHUTDOWN - states, the RPC is unable to be transmitted promptly. By default, gRPC - implementations SHOULD fail such RPCs immediately. This is known as "fail - fast," but the usage of the term is historical. RPCs SHOULD NOT fail as a - result of the channel being in other states (CONNECTING, READY, or IDLE). + If an RPC is issued but the channel is in the TRANSIENT_FAILURE or SHUTDOWN + states, the library cannot transmit the RPC at the moment. By default, the + gRPC library will fail such RPCs immediately. This is known as "fail fast." + RPCs will 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. + When the wait_for_ready option is specified, the library will queue RPCs + until the channel is READY. Any submitted RPCs may still fail before the + READY state is reached for other reasons, e.g., the client channel has been + shut down or the RPC's deadline has been reached.