Table of Contents

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

name string

The name of the circuit breaker.

cache IDistributedCache

The store through which circuit state is shared. Must be genuinely shared across instances for the breaker to coordinate anything.

options IOptions<DistributedCircuitBreakerOptions>

The configuration options for the circuit breaker.

logger ILogger<DistributedCircuitBreaker>

The logger used for diagnostic output.

timeProvider TimeProvider

Optional 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

string

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

operation Func<Task<T>>

The operation to execute within the circuit breaker.

cancellationToken CancellationToken

A token that is observed for cancellation.

Returns

Task<T>

A task that completes with the asynchronous result.

Type Parameters

T

The type returned by the asynchronous operation.

GetStateAsync(CancellationToken)

Gets the current state of the circuit breaker.

public Task<CircuitState> GetStateAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A 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

cancellationToken CancellationToken

A token that is observed for cancellation.

exception Exception

The 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

cancellationToken CancellationToken

A 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

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the reset operation.