Table of Contents

Interface ICircuitBreakerPolicy

Namespace
Excalibur.Dispatch.Resilience
Assembly
Excalibur.Dispatch.dll

Defines the contract for a circuit breaker policy that protects operations from repeated failures.

public interface ICircuitBreakerPolicy
Extension Methods

Remarks

The circuit breaker pattern prevents cascading failures by "tripping" when a threshold of failures is reached, temporarily rejecting all requests. After a cooldown period, it allows limited traffic through to test if the underlying service has recovered.

A policy's configuration is fixed for its lifetime. The values an implementation is created with are the values it uses until it is discarded: no member of this interface changes them, and neither does any later change to the object they were read from. Configuration types in this framework are settable so they can take part in the options pattern -- binding, Configure callbacks and startup validation all require setters -- so a caller may still hold the instance it passed and alter it afterwards. Doing so has no effect on a policy already built from it, on any implementation. To run with different settings, create a new policy; do not mutate and expect the existing one to follow.

Diagnostic properties (ConsecutiveFailures, LastOpenedAt) and events (StateChanged) are kept off this interface so an implementation is not obliged to carry them. Test the policy instance for ICircuitBreakerDiagnostics or ICircuitBreakerEvents to reach them.

Properties

State

Gets the current state of the circuit breaker.

CircuitState State { get; }

Property Value

CircuitState

Methods

ExecuteAsync<TResult>(Func<CancellationToken, Task<TResult>>, Func<TResult, bool>, CancellationToken)

Executes an action through the circuit, treating a returned value as a failure when isFailure says so.

Task<TResult> ExecuteAsync<TResult>(Func<CancellationToken, Task<TResult>> action, Func<TResult, bool> isFailure, CancellationToken cancellationToken)

Parameters

action Func<CancellationToken, Task<TResult>>

The action to execute.

isFailure Func<TResult, bool>

Decides whether a returned result counts as a failure. Not every failure is an exception: a pipeline that returns a failed result would otherwise look healthy to the circuit forever.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<TResult>

The result of the action.

Type Parameters

TResult

The result type.

Exceptions

CircuitBreakerOpenException

Thrown when the circuit is open.

ExecuteAsync<TResult>(Func<CancellationToken, Task<TResult>>, CancellationToken)

Executes an asynchronous operation through the circuit breaker.

Task<TResult> ExecuteAsync<TResult>(Func<CancellationToken, Task<TResult>> action, CancellationToken cancellationToken)

Parameters

action Func<CancellationToken, Task<TResult>>

The action to execute.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<TResult>

The result of the action if successful.

Type Parameters

TResult

The type of the result.

Remarks

This method records the outcome itself. An implementation registers the success, or registers the failure and rethrows, before control returns to the caller. Recording an outcome is not something a caller can do -- or need to do -- separately.

Exceptions

CircuitBreakerOpenException

Thrown when the circuit is open.

ResetAsync(CancellationToken)

Manually returns the circuit breaker to the closed state.

Task ResetAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task

A task that completes once the circuit is closed.

Remarks

When the returned task completes, State is Closed. That is the postcondition an operator depends on: the point of a manual reset is to put a circuit back into service, and a caller that cannot tell when that has happened has to poll or guess. An implementation whose close is asynchronous must therefore await it and publish the closed state before completing, and a close that fails must surface as a faulted task rather than a log line.