Class BackoffCalculatorFactory
- Namespace
- Excalibur.Dispatch.Resilience
- Assembly
- Excalibur.Dispatch.dll
Builds the IBackoffCalculator a retry configuration describes.
public static class BackoffCalculatorFactory
- Inheritance
-
BackoffCalculatorFactory
- Inherited Members
Remarks
Growth law, then jitter, in that order. The strategy selects one of three growth laws and a separate switch decides whether the result is randomised. Previously jitter was decided per strategy arm: the exponential arm hardcoded it OFF, one arm consulted the option, and two strategy names implied it. The out-of-box configuration therefore requested jitter and received none, silently, because the default strategy's arm had already answered the question with a literal. Reading the switch once, here, outside the growth-law selection, is what makes that state unreachable rather than fixed.
This type is public because IBackoffCalculator was not obtainable. The interface has always been public while every implementation of it is internal, so a consumer -- and any sibling package in this framework -- could name the contract and never acquire one. That is what drove callers to the one public thing they could reach, the pure Calculate(int, in BackoffParameters), and it is why a jitter flag grew on BackoffParameters and gave this framework a second, divergent jitter implementation. Supplying the factory removes the pressure that created that divergence instead of forbidding its symptom.
Jitter composes over every law, and it samples below the already-capped delay. The returned calculator caps to the configured maximum FIRST and randomises underneath it. The opposite order -- randomise, then cap -- silently annihilates jitter once the nominal ladder grows past the maximum, because every sampled value then exceeds the cap and the result is exactly the maximum with probability one. That is a thundering herd arriving in lockstep during precisely the sustained outage jitter exists to spread, and it is what this framework shipped.
Methods
Create(BackoffStrategy, RetryOptions)
Creates the calculator for the given strategy and retry options.
public static IBackoffCalculator Create(BackoffStrategy strategy, RetryOptions options)
Parameters
strategyBackoffStrategyThe growth law to apply.
optionsRetryOptionsThe retry options supplying the delays, multiplier and jitter switch.
Returns
- IBackoffCalculator
The calculator.
Exceptions
- ArgumentNullException
optionsis null.- ArgumentOutOfRangeException
strategyis not a declared BackoffStrategy.
Create(BackoffStrategy, in BackoffParameters, bool)
Creates the calculator for the given strategy and backoff schedule.
public static IBackoffCalculator Create(BackoffStrategy strategy, in BackoffParameters parameters, bool useJitter)
Parameters
strategyBackoffStrategyThe growth law to apply.
parametersBackoffParametersThe schedule supplying the base delay, ceiling and multiplier.
useJitterbooltrue to randomise each delay below its capped nominal value, decorrelating callers that failed together; otherwise false for a deterministic schedule.
Returns
- IBackoffCalculator
The calculator.
Remarks
Takes the schedule as a BackoffParameters so a caller that already holds one -- a
transport mapping its own retry options, typically -- can obtain a calculator without restating the
values. Multiplier is clamped up to 1.0 when smaller, which
matches Calculate(int, in BackoffParameters) and that property's
documented behaviour; a default-constructed schedule therefore yields a flat ladder rather than
throwing.
Exceptions
- ArgumentOutOfRangeException
strategyis not a declared BackoffStrategy.