Table of Contents

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

strategy BackoffStrategy

The growth law to apply.

options RetryOptions

The retry options supplying the delays, multiplier and jitter switch.

Returns

IBackoffCalculator

The calculator.

Exceptions

ArgumentNullException

options is null.

ArgumentOutOfRangeException

strategy is 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

strategy BackoffStrategy

The growth law to apply.

parameters BackoffParameters

The schedule supplying the base delay, ceiling and multiplier.

useJitter bool

true 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

strategy is not a declared BackoffStrategy.