Class DistributedCircuitBreaker
- Namespace
- Excalibur.Dispatch.Resilience.Polly
- Assembly
- Excalibur.Dispatch.Resilience.Polly.dll
A circuit breaker whose OPEN/HALF-OPEN/CLOSED state is shared, through an IDistributedCache, with every instance configured against the same store and name.
public class DistributedCircuitBreaker : IDistributedCircuitBreaker, IAsyncDisposable
- Inheritance
-
DistributedCircuitBreaker
- Implements
- Inherited Members
- Extension Methods
Remarks
What is shared. The circuit state, and only the circuit state. When any instance trips it
writes Open to the store; every other instance short-circuits on its next call, so a failing
dependency is shed fleet-wide rather than by each replica in turn. Recovery is shared the same way:
the first instance past the break deadline moves the shared state to half-open, and the successes
that close it are visible to all.
What is local. The failure and success counting that decides WHEN to trip. Each instance
evaluates FailureRatio, MinimumThroughput, SamplingDuration and
ConsecutiveFailureThreshold over its own traffic, so those thresholds are per-instance and
not fleet-wide totals. This is a stated design constraint rather than an omission:
IDistributedCache offers no atomic increment and no compare-and-swap, so a shared
counter can only be maintained by a read-modify-write that loses updates between instances — under
which the breaker under-counts and opens late or never. A per-instance count is exact and its
meaning is stated; a shared count over this abstraction is neither.
Requires an IDistributedCache that is genuinely shared across instances. Backed by an in-process cache each replica trips independently and nothing is coordinated.
Constructors
DistributedCircuitBreaker(string, IDistributedCache, IOptions<DistributedCircuitBreakerOptions>, ILogger<DistributedCircuitBreaker>, TimeProvider?)
Initializes a new instance of the DistributedCircuitBreaker class.
public DistributedCircuitBreaker(string name, IDistributedCache cache, IOptions<DistributedCircuitBreakerOptions> options, ILogger<DistributedCircuitBreaker> logger, TimeProvider? timeProvider = null)
Parameters
namestringThe name of the circuit breaker.
cacheIDistributedCacheThe store through which circuit state is shared. Must be genuinely shared across instances for the breaker to coordinate anything.
optionsIOptions<DistributedCircuitBreakerOptions>The configuration options for the circuit breaker.
loggerILogger<DistributedCircuitBreaker>The logger used for diagnostic output.
timeProviderTimeProviderOptional time provider used for all trip-boundary, window, and state-transition timestamps. Defaults to System. Inject a controllable provider to make the open-decision boundary deterministically testable.
Properties
Name
Gets the circuit breaker name, used for cache key generation and logging.
public string Name { get; }
Property Value
Methods
DisposeAsync()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
public ValueTask DisposeAsync()
Returns
- ValueTask
A task that represents the asynchronous dispose operation.
ExecuteAsync<T>(Func<Task<T>>, CancellationToken)
Executes an operation with distributed circuit breaker protection.
public Task<T> ExecuteAsync<T>(Func<Task<T>> operation, CancellationToken cancellationToken)
Parameters
operationFunc<Task<T>>The operation to execute within the circuit breaker.
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- Task<T>
A task that completes with the asynchronous result.
Type Parameters
TThe type returned by the asynchronous
operation.
GetStateAsync(CancellationToken)
Gets the current state of the circuit breaker.
public Task<CircuitState> GetStateAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- Task<CircuitState>
A task that completes with the distributed circuit state.
RecordFailureAsync(CancellationToken, Exception?)
Records a failure in the distributed state.
public Task RecordFailureAsync(CancellationToken cancellationToken, Exception? exception = null)
Parameters
cancellationTokenCancellationTokenA token that is observed for cancellation.
exceptionExceptionThe exception being evaluated.
Returns
- Task
A task that completes when the update is persisted.
RecordSuccessAsync(CancellationToken)
Records a success in the distributed state.
public Task RecordSuccessAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- Task
A task that completes when the update is persisted.
ResetAsync(CancellationToken)
Resets the circuit breaker across all instances.
public Task ResetAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the reset operation.