You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`ShouldHandle`| Predicate that handles all exceptions except `OperationCanceledException`. | Predicate that determines what results and exceptions are handled by the retry strategy. |
65
65
|`MaxHedgedAttempts`| 1 | The maximum number of hedged actions to use, in addition to the original action. |
66
66
|`Delay`| 2 seconds | The maximum waiting time before spawning a new hedged action. |
67
67
|`ActionGenerator`| Returns the original callback that was passed to the hedging strategy. | Generator that creates hedged actions. |
68
-
|`DelayGenerator`|`null`| Used for generating custom delays for hedging. If `null` then `Delay` is used.|
68
+
|`DelayGenerator`|`null`| Used for generating custom delays for hedging. |
69
69
|`OnHedging`|`null`| Event that is raised when a hedging is performed. |
70
70
71
71
You can use the following special values for `Delay` or in `DelayGenerator`:
72
72
73
73
-`0 seconds` - the hedging strategy immediately creates a total of `MaxHedgedAttempts` and completes when the fastest acceptable result is available.
74
74
-`-1 millisecond` - this value indicates that the strategy does not create a new hedged task before the previous one completes. This enables scenarios where having multiple concurrent hedged tasks can cause side effects.
75
75
76
+
> [!NOTE]
77
+
> If both `Delay` and `DelayGenerator` are specified then `Delay` will be ignored.
78
+
76
79
## Concurrency modes
77
80
78
81
In the sections below, explore the different concurrency modes available in the hedging strategy. The behavior is primarily controlled by the `Delay` property value.
Copy file name to clipboardExpand all lines: docs/strategies/retry.md
+104
Original file line number
Diff line number
Diff line change
@@ -108,6 +108,110 @@ new ResiliencePipelineBuilder<HttpResponseMessage>().AddRetry(optionsExtractDela
108
108
|`OnRetry`|`null`| Action executed when retry occurs. |
109
109
|`MaxDelay`|`null`| Caps the calculated retry delay to a specified maximum duration. |
110
110
111
+
## Calculation of the next delay
112
+
113
+
If the `ShouldHandle` predicate returns `true` and the next attempt number is not greater than `MaxRetryAttempts` then the retry strategy calculates the next delay.
114
+
115
+
There are many properties that may contribute to this calculation:
116
+
117
+
-`BackoffType`: Specifies which calculation algorithm should run.
118
+
-`Delay`: If only this property is specified then it will be used as-is. If others are also specified then this will be used as a *base delay*.
119
+
-`DelayGenerator`: If specified, will override other property-based calculations, **except** if it returns `null` or a negative `TimeSpan`, in which case the other property-based calculations are used.
120
+
-`MaxDelay`: If specified, caps the delay if the calculated delay is greater than this value, **except** if `DelayGenerator` is used, where no capping is applied.
121
+
-`UseJitter`: If enabled, then adds a random value between between -25% of `Delay` and +25% of `Delay`, **except** if `BackoffType` is `Exponential`, where a bit more complex jitter calculation is used.
122
+
123
+
> [!IMPORTANT]
124
+
> The summarized description below is an implementation detail. It may change in the future without notice.
125
+
126
+
The `BackoffType` property's data type is the [`DelayBackoffType`](xref:Polly.DelayBackoffType) enumeration. This primarily controls how the calculation is done.
127
+
128
+
### Constant
129
+
130
+
Even though the `Constant` name could imply that only the `Delay` property is used, in reality all the above listed properties are used.
131
+
132
+
Step 1: Calculating the base delay:
133
+
134
+
- If `UseJitter` is set to `false` and `Delay` is specified then `Delay` will be used.
135
+
- If `UseJitter` is set to `true` and `Delay` is specified then a random value is added to the `Delay`.
136
+
- The random value is between -25% and +25% of `Delay`.
137
+
138
+
Step 2: Capping the delay if needed:
139
+
140
+
- If `MaxDelay` is not set then the previously calculated delay will be used.
141
+
- If `MaxDelay` is set and the previously calculated delay is greater than `MaxDelay` then `MaxDelay` will be used.
142
+
143
+
Step 3: Using the generator if supplied
144
+
145
+
- If the returned `TimeSpan` of the `DelayGenerator` method call is positive then it will be used.
146
+
- If the returned `TimeSpan` of the `DelayGenerator` method call is negative then it will use the step 2's result.
147
+
- If the `DelayGenerator` method call is `null` then it will use the step 2's result.
148
+
149
+
> [!NOTE]
150
+
> The `DelayGenerator`'s returned value is not capped with the `MaxDelay`.
151
+
152
+
#### Constant examples
153
+
154
+
The delays column contains an example series of five values to depict the patterns.
This algorithm increases the delays for every attempt in an exponential fashion if no jitter is used.
190
+
191
+
- If `UseJitter` is set to `false` and `Delay` is specified then squaring actual attempt number multiplied by the `Delay` will be used (*`attempt^2 * delay`*).
192
+
- If `UseJitter` is set to `true` and the `Delay` is specified then a `DecorrelatedJitterBackoffV2` formula (based on [Polly.Contrib.WaitAndRetry](https://github.com/Polly-Contrib/Polly.Contrib.WaitAndRetry)) will be used.
193
+
194
+
> [!NOTE]
195
+
> Because the jitter calculation is based on the newly calculated delay, the new delay could be less than the previous value.
196
+
197
+
Step 2 and 3 are the same as for the Constant algorithm.
198
+
199
+
#### Exponential examples
200
+
201
+
The delays column contains an example series of five values to depict the patterns.
> For more details please check out the [`RetryHelper`](https://github.com/App-vNext/Polly/blob/main/src/Polly.Core/Retry/RetryHelper.cs)
213
+
> and the [`RetryResilienceStrategy`](https://github.com/App-vNext/Polly/blob/main/src/Polly.Core/Retry/RetryResilienceStrategy.cs) classes.
214
+
111
215
## Diagrams
112
216
113
217
Let's suppose we have a retry strategy with `MaxRetryAttempts`: `2`.
0 commit comments