Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
First draft of cancellation doc (#1137)
- Loading branch information
Showing
1 changed file
with
72 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
--- | ||
title: Cancellation | ||
description: >- | ||
Explains how and when to cancel RPCs. | ||
--- | ||
|
||
### Overview | ||
|
||
When a gRPC client is no longer interested in the result of an RPC call, it may | ||
_cancel_ to signal this discontinuation of interest to the server. | ||
[Deadline](https://grpc.io/docs/guides/deadlines/) expiration and I/O errors | ||
also trigger cancellation. When an RPC is cancelled, the server should stop | ||
any ongoing computation and end its side of the stream. Often, servers are also | ||
clients to upstream servers, so that cancellation operation should ideally | ||
propagate to all ongoing computation in the system that was initiated due to | ||
the original client RPC call. | ||
|
||
A client may cancel an RPC for several reasons. The data it requested may have | ||
been made irrelevant or the author of the client may want to be a good citizen | ||
of the server and conserve compute resources. | ||
|
||
```mermaid | ||
sequenceDiagram | ||
Client ->> Server 1: Cancel | ||
Server 1 ->> Server 2: Cancel | ||
``` | ||
|
||
|
||
### Cancelling an RPC Call on the Client Side | ||
|
||
A client cancels an RPC call by calling a method on the call object or, in some | ||
languages, on the accompanying context object. While gRPC clients do not | ||
provide additional details to the server about the reason for the cancellation, | ||
the cancel API call takes a string describing the reason, which will result in | ||
a client-side exception and/or log containing the provided reason. When a | ||
server is notified of the cancellation of an RPC, the application-provided | ||
server handler may be busy processing the request. The gRPC library in general | ||
does not have a mechanism to interrupt the application-provided server handler, | ||
so the server handler must coordinate with the gRPC library to ensure that | ||
local processing of the request ceases. Therefore, if an RPC is long-lived, | ||
its server handler must periodically check if the RPC it is servicing has been | ||
cancelled and if it has, cease processing. Some languages will also | ||
support automatic cancellation of anyoutgoing RPCs, while in others, the author | ||
of the server handler is responsible for this. | ||
|
||
|
||
```mermaid | ||
flowchart LR | ||
subgraph Client | ||
end | ||
subgraph Server1 | ||
direction TB | ||
cancelled{cancelled?} -->|false| perform("perform some work") | ||
perform --> cancelled | ||
cancelled -->|true| cleanup("cancel upstream RPCs") | ||
cleanup --> exit("exit RPC handler") | ||
end | ||
subgraph Server2 | ||
end | ||
Client -->|CANCEL| Server1 | ||
Server1 -->|CANCEL| Server2 | ||
``` | ||
|
||
### Language Support | ||
|
||
| Language | Example | Notes | | ||
|----------|----------------|----------------------------------| | ||
| Java |[Example](https://github.com/grpc/grpc-java/tree/master/examples/src/main/java/io/grpc/examples/cancellation)|Automatically cancels outgoing RPCs| | ||
| Go |[Example](https://github.com/grpc/grpc-go/tree/master/examples/features/cancellation)|Automatically cancels outgoing RPCs| | ||
| C++ |Upcoming|Automatically cancels outgoing RPCs| | ||
| Python | [Example](https://github.com/grpc/grpc/tree/master/examples/python/cancellation)|| |