From b42317b32dc037c6af0dac9d303bc71c5eb8b03d Mon Sep 17 00:00:00 2001 From: Purnesh Dixit Date: Fri, 20 Dec 2024 13:31:46 +0530 Subject: [PATCH] Address more documentation comments from doug --- .../en/docs/guides/server-graceful-stop.md | 47 +++++++++++-------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/content/en/docs/guides/server-graceful-stop.md b/content/en/docs/guides/server-graceful-stop.md index 3b360f6014..0fe1718706 100644 --- a/content/en/docs/guides/server-graceful-stop.md +++ b/content/en/docs/guides/server-graceful-stop.md @@ -1,7 +1,8 @@ --- -title: Gracefull Shutdown +title: Graceful Shutdown description: >- - Explains how to gracefully stop/shutdown a gRPC server. + Explains how to gracefully shut down [or stop, if you prefer] a gRPC server + to avoid causing RPC failures for connected clients. --- ### Overview @@ -12,13 +13,17 @@ accepted. The "Graceful shutdown function" facilitates this process, allowing the server to transition smoothly without abruptly terminating active connections. -When the "Graceful shutdown function" is called, the server immediately stops -accepting new RPCs. In-flight RPCs are allowed to continue until they complete -or a specified deadline is reached. Once all active RPCs finish or the deadline -expires, the server shuts down completely. +When the "Graceful shutdown function" is called, the server immediately +notifies all clients that they should stop sending new RPCs. Then after the +clients have received that notification, the server will stop accepting new +RPCs. In-flight RPCs are allowed to continue until they complete or a specified +deadline is reached. Once all active RPCs finish or the deadline expires, the +server shuts down completely. -While a graceful shutdown is optional, it's highly recommended. You can -shutdown without a graceful shutdown first but that would not be recommended. +Because graceful shutdown helps prevent clients from encountering RPC failures, +it should be used if possible. However, gRPC also provides a forceful shutdown +mechanism which will immediately cause the server to stop serving and close all +connections, which results in the failure of any in-flight RPCs. ### How to do Graceful Server Shutdown @@ -26,7 +31,7 @@ The exact implementation of the "Graceful shutdown function" varies depending on the programming language you are using. However, the general pattern involves: -- Initiating the graceful shutdown process by calling "Graceful shutdown +- Initiating the graceful shutdown process by calling the "Graceful shutdown function" on your gRPC server object. This function blocks until all currently running RPCs complete. This ensures that in-flight requests are allowed to finish processing. @@ -39,7 +44,7 @@ involves: prevents indefinite blocking. The following shows the sequence of events that occur, when a server's graceful -stop is invoked, in-flight RPCs continue to prorcess, but new RPCs are +stop is invoked, in-flight RPCs continue to process, but new RPCs are rejected. If some in-flight RPCs are not finished in time, server is forcefully shutdown. ```mermaid @@ -48,7 +53,7 @@ Client->>Server: New RPC Request 1 Client->>Server: New RPC Request 2 Server-->>Server: Graceful Shutdown Invoked Server->>Client: Continues Processing In-Flight RPCs -Client->>Client: Detects server shutdown and go find other servers if available +Client->>Client: Detects server shutdown and go finds other servers if available alt RPCs complete within timeout Server->>Client: Completes RPC 1 Server->>Client: Completes RPC 2 @@ -63,19 +68,21 @@ The following is a state based view stateDiagram-v2 [*] --> RUNNING : Server Started RUNNING --> GRACEFUL_STOP_INITIATED : Graceful Stop Called (with Timeout) - GRACEFUL_STOP_INITIATED --> GRACEFUL_STOPPING : Reject New RPCs - GRACEFUL_STOPPING --> TERMINATED : Complete In-Flight RPCs (Before Timeout) - GRACEFUL_STOPPING --> FORCE_STOP : Timeout Reached - FORCE_STOP --> TERMINATED : Force Terminate Pending RPCs and Shutdown + GRACEFUL_STOP_INITIATED --> GRACEFUL_STOPPING + GRACEFUL_STOPPING --> TERMINATED : In-Flight RPCs Compeleted (Before Timeout) + GRACEFUL_STOPPING --> TIMER_EXPIRED : Timeout Reached + TIMER_EXPIRED --> TERMINATED : Force Stop Called ``` ### Language Support -| Language | Example | -|----------|-------------------| -| Java | [Java example] | -| Go | [Go example] | -| Python | | +| Language | Example | +|----------|------------------| +| C++ | | +| Go | [Go Example] | +| Java | [Java Example] | +| Python | | + [Go example]: https://github.com/grpc/grpc-go/tree/master/examples/features/gracefulstop [Java example]: https://github.com/grpc/grpc-java/tree/master/examples/example-hostname/src/main/java/io/grpc/examples/hostname