From 640b83575e5547f1358bc0b2617f73cd156e5e87 Mon Sep 17 00:00:00 2001
From: Richard Belleville <rbellevi@google.com>
Date: Mon, 5 Jun 2023 13:17:49 -0700
Subject: [PATCH] First draft of cancellation doc (#1137)

---
 content/en/docs/guides/cancellation.md | 72 ++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 content/en/docs/guides/cancellation.md

diff --git a/content/en/docs/guides/cancellation.md b/content/en/docs/guides/cancellation.md
new file mode 100644
index 0000000000..6b62cd6478
--- /dev/null
+++ b/content/en/docs/guides/cancellation.md
@@ -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)||