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
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
actionFunc<CancellationToken, Task<TResult>>The action to execute.
isFailureFunc<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.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<TResult>
The result of the action.
Type Parameters
TResultThe 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
actionFunc<CancellationToken, Task<TResult>>The action to execute.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<TResult>
The result of the action if successful.
Type Parameters
TResultThe 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
cancellationTokenCancellationTokenCancellation 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.