[Docs] Improve diagrams for hedging cancellation (App-vNext#1975)

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

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.

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