From 3e2164e50b7dcd2021c95470a6b80a0c032607c5 Mon Sep 17 00:00:00 2001
From: martintmk <103487740+martintmk@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:17:58 +0100
Subject: [PATCH] [Docs] Improve diagrams for hedging cancellation (#1975)

---
 docs/pipelines/index.md    |  8 ++++++++
 docs/strategies/hedging.md | 19 ++++++++++++++++++-
 docs/strategies/timeout.md |  7 +++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/pipelines/index.md b/docs/pipelines/index.md
index 63d4f71d13b..11fc41a8d68 100644
--- a/docs/pipelines/index.md
+++ b/docs/pipelines/index.md
@@ -201,6 +201,8 @@ sequenceDiagram
     deactivate T
     T-->>T: Times out
     T->>D: Propagates cancellation
+    D-->>D: Cancellation of callback
+    D->>T: Cancellation finished
     deactivate D
     T->>R: Throws <br/>TimeoutRejectedException
     R-->>R: Sleeps
@@ -281,6 +283,8 @@ sequenceDiagram
     T-->>T: Times out
     T->>R: Propagates cancellation
     R->>D: Propagates cancellation
+    D-->>D: Cancellation of callback
+    D->>T: Cancellation finished
     deactivate D
 
     T->>P: Throws <br/>TimeoutRejectedException
@@ -348,6 +352,8 @@ sequenceDiagram
     deactivate TI
     Note over TI: Wait end
     TI->>D: Propagates cancellation
+    D-->>D: Cancellation of callback
+    D->>TI: Cancellation finished
     deactivate D
     TI->>R: Throws <br/>TimeoutRejectedException
 
@@ -365,6 +371,8 @@ sequenceDiagram
     TO->>R: Propagates cancellation
     R->>TI: Propagates cancellation
     TI->>D: Propagates cancellation
+    D-->>D: Cancellation of callback
+    D->>TO: Cancellation finished
     deactivate TI
     deactivate D
     TO->>P: Throws <br/>TimeoutRejectedException
diff --git a/docs/strategies/hedging.md b/docs/strategies/hedging.md
index 20b5674f07d..515ca0dabf1 100644
--- a/docs/strategies/hedging.md
+++ b/docs/strategies/hedging.md
@@ -144,14 +144,23 @@ sequenceDiagram
     D-->>D: Processes R2<br/> quickly
     D->>H: Returns result (R2)
     deactivate D
+    deactivate D
+
     H->>D: Propagates cancellation (R1)
+    activate D
+    D-->>D: Cancellation of pending actions (R1)
+    deactivate D
+    D->>H: Cancellation finished (R1)
+
     deactivate H
 
-    deactivate D
     H->>P: Returns result (R2)
     P->>C: Returns result (R2)
 ```
 
+> [!NOTE]
+> Notice that the hedging waits until all additional pending actions are cancelled before returning the accepted result. Therefore it's important for the hedged actions to respect the cancellation token passed to the execution. If the cancellation token is not correctly respected, the hedging is unnecessarily delayed.
+
 ### Fallback mode
 
 In fallback mode, the `Delay` value should be less than `TimeSpan.Zero`. This mode allows only a single execution to proceed at a given time.
@@ -258,14 +267,22 @@ sequenceDiagram
     HUC-->>HUC: Processes R2<br/> quickly ...
     HUC->>-H: Returns result (R2)
 
+    deactivate HUC
+
     H->>HUC: Propagates cancellation (R1)
+    activate HUC
+    HUC-->>HUC: Cancellation of pending actions (R1)
     deactivate HUC
+    HUC->>H: Cancellation finished (R1)
 
     deactivate H
     H->>P: Returns result (R2)
     P->>C: Returns result (R2)
 ```
 
+> [!NOTE]
+> Notice that the hedging waits until all additional pending actions are cancelled before returning the accepted result. Therefore it's important for the hedged actions to respect the cancellation token passed to the execution. If the cancellation token is not correctly respected, the hedging is unnecessarily delayed.
+
 #### Parallel: unhappy path sequence diagram
 
 The hedging strategy triggers because the `Delay` is set to zero. It fails because all requests fail.
diff --git a/docs/strategies/timeout.md b/docs/strategies/timeout.md
index 961a1e6bb45..66753fa71a2 100644
--- a/docs/strategies/timeout.md
+++ b/docs/strategies/timeout.md
@@ -165,12 +165,19 @@ sequenceDiagram
     D-->>D: Performs <br/>long-running <br/>operation
     T-->>T: Times out
     deactivate T
+
     T->>D: Propagates cancellation
+    D-->>D: Cancellation of callback
+    D->>T: Cancellation finished
     deactivate D
+
     T->>P: Throws <br/>TimeoutRejectedException
     P->>C: Propagates exception
 ```
 
+> [!IMPORTANT]
+> Notice that the timeout waits until the callback is cancelled before throwing `TimeoutRejectedException`. Therefore it's important for the callbacks to respect the cancellation token passed to the execution. If the cancellation token is not correctly respected, the timeout is unnecessarily delayed.
+
 ## Anti-patterns
 
 Over the years, many developers have used Polly in various ways. Some of these