From 63ad8717c224d292e5d0570f1d7b55db8e9e2c1c Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Fri, 26 Jul 2024 16:13:57 -0700 Subject: [PATCH] docs/guides/deadlines: Replace "request" with "RPC" (#1336) Not all usages of request were changed, but any that were talking about the deadline of a request were changed, because requests don't have deadlines. Only RPCs have deadlines. I also made it more clear at which point a timeout would start from within gRPC. --- content/en/docs/guides/deadlines.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/content/en/docs/guides/deadlines.md b/content/en/docs/guides/deadlines.md index 6c841ed..ec20e8e 100644 --- a/content/en/docs/guides/deadlines.md +++ b/content/en/docs/guides/deadlines.md @@ -15,9 +15,10 @@ improve the resource utilization and latency of your system. Note that while some language APIs have the concept of a __deadline__, others use the idea of a __timeout__. When an API asks for a deadline, you provide a -point in time which the request should not go past. A timeout is the max -duration of time that the request can take. For simplicity, we will only refer -to deadline in this document. +point in time which the call should not go past. A timeout is the max duration +of time that the call can take. A timeout can be converted to a deadline by +adding the timeout to the current time when the application starts a call. For +simplicity, we will only refer to deadline in this document. ### Deadlines on the Client @@ -33,7 +34,7 @@ will give up and fail the RPC with the `DEADLINE_EXCEEDED` status. ### Deadlines on the Server -A server might receive requests from a client with an unrealistically short +A server might receive RPCs from a client with an unrealistically short deadline that would not give the server enough time to ever respond in time. This would result in the server just wasting valuable resources and in the worst case scenario, crash the server. A gRPC server deals with this situation by @@ -41,8 +42,8 @@ automatically cancelling a call (`CANCELLED` status) once a deadline set by the client has passed. Please note that the server application is responsible for stopping any activity -it has spawned to service the request. If your application is running a -long-running process you should periodically check if the request that initiated +it has spawned to service the RPC. If your application is running a +long-running process you should periodically check if the RPC that initiated it has been cancelled and if so, stop the processing. #### Deadline Propagation @@ -50,7 +51,7 @@ it has been cancelled and if so, stop the processing. Your server might need to call another server to produce a response. In these cases where your server also acts as a client you would want to honor the deadline set by the original client. Automatically propagating the deadline from -an incoming request to an outgoing one is supported by some gRPC +an incoming RPC to an outgoing one is supported by some gRPC implementations. In some languages this behavior needs to be explicitly enabled (e.g. C++) and in others it is enabled by default (e.g. Java and Go). Using this capability lets you avoid the error-prone approach of manually @@ -108,4 +109,4 @@ sequenceDiagram - [Deadlines blogpost] -[Deadlines blogpost]: https://grpc.io/blog/deadlines/ \ No newline at end of file +[Deadlines blogpost]: https://grpc.io/blog/deadlines/