Class CircuitBreaker

Provides circuit breaker functionality to provide stability when working with "dangerous" operations, e.g. calls to remote systems

Transitions through three states:

  • In *Closed* state, calls pass through until the maxFailures count is reached. This causes the circuit breaker to open. Both exceptions and calls exceeding callTimeout are considered failures.
  • In *Open* state, calls fail-fast with an exception. After resetTimeout, circuit breaker transitions to half-open state.
  • In *Half-Open* state, the first call will be allowed through, if it succeeds the circuit breaker will reset to closed state. If it fails, the circuit breaker will re-open to open state. All calls beyond the first that execute while the first is running will fail-fast with an exception.
Inheritance
object
CircuitBreaker
Inherited Members
Namespace: Akka.Pattern
Assembly: Akka.dll
Syntax
public class CircuitBreaker

Constructors

| Edit this page View Source

CircuitBreaker(IScheduler, int, TimeSpan, TimeSpan)

Create a new CircuitBreaker

Declaration
public CircuitBreaker(IScheduler scheduler, int maxFailures, TimeSpan callTimeout, TimeSpan resetTimeout)
Parameters
Type Name Description
IScheduler scheduler

Reference to Akka scheduler
int maxFailures

Maximum number of failures before opening the circuit
TimeSpan callTimeout

TimeSpan of time after which to consider a call a failure
TimeSpan resetTimeout

TimeSpan of time after which to attempt to close the circuit
| Edit this page View Source

CircuitBreaker(IScheduler, int, TimeSpan, TimeSpan, TimeSpan, double)

Create a new CircuitBreaker

Declaration
public CircuitBreaker(IScheduler scheduler, int maxFailures, TimeSpan callTimeout, TimeSpan resetTimeout, TimeSpan maxResetTimeout, double exponentialBackoffFactor)
Parameters
Type Name Description
IScheduler scheduler

Reference to Akka scheduler
int maxFailures

Maximum number of failures before opening the circuit
TimeSpan callTimeout

TimeSpan of time after which to consider a call a failure
TimeSpan resetTimeout

TimeSpan of time after which to attempt to close the circuit
TimeSpan maxResetTimeout

The maximum reset timeout when using exponential backoff
double exponentialBackoffFactor

The factor by which the reset timeout increases when using exponential backoff
| Edit this page View Source

CircuitBreaker(IScheduler, int, TimeSpan, TimeSpan, TimeSpan, double, double)

Create a new CircuitBreaker

Declaration
public CircuitBreaker(IScheduler scheduler, int maxFailures, TimeSpan callTimeout, TimeSpan resetTimeout, TimeSpan maxResetTimeout, double exponentialBackoffFactor, double randomFactor)
Parameters
Type Name Description
IScheduler scheduler

Reference to Akka scheduler
int maxFailures

Maximum number of failures before opening the circuit
TimeSpan callTimeout

TimeSpan of time after which to consider a call a failure
TimeSpan resetTimeout

TimeSpan of time after which to attempt to close the circuit
TimeSpan maxResetTimeout
double exponentialBackoffFactor
double randomFactor

After calculation of the exponential back-off an additional random delay based on this factor is added, e.g. 0.2 adds up to 20% delay. randomFactor should be in range 0.0 (inclusive) and 1.0 (inclusive). In order to skip this additional delay pass in 0.

Properties

| Edit this page View Source

CallTimeout

Gets the timeout after which a call is considered a failure.

Declaration
public TimeSpan CallTimeout { get; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

CurrentFailureCount

Retrieves current failure count.

Declaration
public long CurrentFailureCount { get; }
Property Value
Type Description
long
| Edit this page View Source

ExponentialBackoffFactor

Gets the factor by which the reset timeout increases when using exponential backoff.

Declaration
public double ExponentialBackoffFactor { get; }
Property Value
Type Description
double
| Edit this page View Source

IsClosed

Return true if the internal state is Closed. WARNING: It is a "power API" call which you should use with care. Ordinal use cases of CircuitBreaker expects a remote call to return Future, as in WithCircuitBreaker(Func<CancellationToken, Task>). So, if you check the state by yourself, and make a remote call outside CircuitBreaker, you should manage the state yourself.

Declaration
public bool IsClosed { get; }
Property Value
Type Description
bool
| Edit this page View Source

IsHalfOpen

Return true if the internal state is HalfOpen. WARNING: It is a "power API" call which you should use with care. Ordinal use cases of CircuitBreaker expects a remote call to return Future, as in withCircuitBreaker. So, if you check the state by yourself, and make a remote call outside CircuitBreaker, you should manage the state yourself.

Declaration
public bool IsHalfOpen { get; }
Property Value
Type Description
bool
| Edit this page View Source

IsOpen

Return true if the internal state is Open. WARNING: It is a "power API" call which you should use with care. Ordinal use cases of CircuitBreaker expects a remote call to return Future, as in WithCircuitBreaker(Func<CancellationToken, Task>). So, if you check the state by yourself, and make a remote call outside CircuitBreaker, you should manage the state yourself.

Declaration
public bool IsOpen { get; }
Property Value
Type Description
bool
| Edit this page View Source

LastCaughtException

Declaration
public Exception LastCaughtException { get; }
Property Value
Type Description
Exception
| Edit this page View Source

MaxFailures

Gets the maximum number of failures allowed before the circuit breaker opens.

Declaration
public int MaxFailures { get; }
Property Value
Type Description
int
| Edit this page View Source

MaxResetTimeout

Gets the maximum reset timeout for exponential backoff.

Declaration
public TimeSpan MaxResetTimeout { get; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

RandomFactor

Gets the random factor used to add jitter to the reset timeout.

Declaration
public double RandomFactor { get; }
Property Value
Type Description
double
| Edit this page View Source

ResetTimeout

Gets the timeout after which to attempt to close the circuit if it is open.

Declaration
public TimeSpan ResetTimeout { get; }
Property Value
Type Description
TimeSpan
| Edit this page View Source

Scheduler

Gets the scheduler used for circuit breaker timing operations.

Declaration
public IScheduler Scheduler { get; }
Property Value
Type Description
IScheduler

Methods

| Edit this page View Source

Create(IScheduler, int, TimeSpan, TimeSpan)

Create a new CircuitBreaker

Declaration
public static CircuitBreaker Create(IScheduler scheduler, int maxFailures, TimeSpan callTimeout, TimeSpan resetTimeout)
Parameters
Type Name Description
IScheduler scheduler

Reference to Akka scheduler
int maxFailures

Maximum number of failures before opening the circuit
TimeSpan callTimeout

TimeSpan of time after which to consider a call a failure
TimeSpan resetTimeout

TimeSpan of time after which to attempt to close the circuit
Returns
Type Description
CircuitBreaker

A new CircuitBreaker instance
| Edit this page View Source

Fail()

Mark a failed call through CircuitBreaker. Sometimes the callee of CircuitBreaker sends back a message to the caller Actor. In such a case, it is convenient to mark a failed call instead of using Future via WithCircuitBreaker(Func<CancellationToken, Task>) or WithCircuitBreaker<T>(Func<CancellationToken, Task<T>>)

Declaration
public void Fail()
| Edit this page View Source

OnClose(Action)

Adds a callback to execute when circuit breaker state closes

Declaration
public CircuitBreaker OnClose(Action callback)
Parameters
Type Name Description
Action callback

Action Handler to be invoked on state change
Returns
Type Description
CircuitBreaker

CircuitBreaker for fluent usage
| Edit this page View Source

OnHalfOpen(Action)

Adds a callback to execute when circuit breaker transitions to half-open

Declaration
public CircuitBreaker OnHalfOpen(Action callback)
Parameters
Type Name Description
Action callback

Action Handler to be invoked on state change
Returns
Type Description
CircuitBreaker

CircuitBreaker for fluent usage
| Edit this page View Source

OnOpen(Action)

Adds a callback to execute when circuit breaker opens

Declaration
public CircuitBreaker OnOpen(Action callback)
Parameters
Type Name Description
Action callback

Action Handler to be invoked on state change
Returns
Type Description
CircuitBreaker

CircuitBreaker for fluent usage
| Edit this page View Source

Succeed()

Mark a successful call through CircuitBreaker. Sometimes the callee of CircuitBreaker sends back a message to the caller Actor. In such a case, it is convenient to mark a successful call instead of using Future via WithCircuitBreaker(Func<CancellationToken, Task>) or WithCircuitBreaker<T>(Func<CancellationToken, Task<T>>)

Declaration
public void Succeed()
| Edit this page View Source

WithCircuitBreaker(Func<CancellationToken, Task>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
public Task WithCircuitBreaker(Func<CancellationToken, Task> body)
Parameters
Type Name Description
Func<CancellationToken, Task> body

Call needing protected
Returns
Type Description
Task

Task containing the call result
| Edit this page View Source

WithCircuitBreaker(Func<Task>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
[Obsolete("Use WithCircuitBreaker() that accepts functions with CancellationToken parameter. Since 1.5.42")]
public Task WithCircuitBreaker(Func<Task> body)
Parameters
Type Name Description
Func<Task> body

Call needing protected
Returns
Type Description
Task

Task containing the call result
| Edit this page View Source

WithCircuitBreaker<T>(Func<CancellationToken, Task<T>>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
public Task<T> WithCircuitBreaker<T>(Func<CancellationToken, Task<T>> body)
Parameters
Type Name Description
Func<CancellationToken, Task<T>> body

Call needing protected
Returns
Type Description
Task<T>

Task containing the call result
Type Parameters
Name Description
T

The Type returned by the protected function
| Edit this page View Source

WithCircuitBreaker<T>(Func<Task<T>>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
[Obsolete("Use WithCircuitBreaker() that accepts functions with CancellationToken parameter. Since 1.5.42")]
public Task<T> WithCircuitBreaker<T>(Func<Task<T>> body)
Parameters
Type Name Description
Func<Task<T>> body

Call needing protected
Returns
Type Description
Task<T>

Task containing the call result
Type Parameters
Name Description
T

The Type returned by the protected function
| Edit this page View Source

WithCircuitBreaker<TState>(TState, Func<TState, CancellationToken, Task>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
public Task WithCircuitBreaker<TState>(TState state, Func<TState, CancellationToken, Task> body)
Parameters
Type Name Description
TState state

The state object will be passed into the protected function during invocation
Func<TState, CancellationToken, Task> body

Call needing protected
Returns
Type Description
Task

Task containing the call result
Type Parameters
Name Description
TState

The Type of the state object passed into the protected function
| Edit this page View Source

WithCircuitBreaker<TState>(TState, Func<TState, Task>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
[Obsolete("Use WithCircuitBreaker() that accepts functions with CancellationToken parameter. Since 1.5.42")]
public Task WithCircuitBreaker<TState>(TState state, Func<TState, Task> body)
Parameters
Type Name Description
TState state

The state object will be passed into the protected function during invocation
Func<TState, Task> body

Call needing protected
Returns
Type Description
Task

Task containing the call result
Type Parameters
Name Description
TState

The Type of the state object passed into the protected function
| Edit this page View Source

WithCircuitBreaker<T, TState>(TState, Func<TState, CancellationToken, Task<T>>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
public Task<T> WithCircuitBreaker<T, TState>(TState state, Func<TState, CancellationToken, Task<T>> body)
Parameters
Type Name Description
TState state

The state object will be passed into the protected function during invocation
Func<TState, CancellationToken, Task<T>> body

Call needing protected
Returns
Type Description
Task<T>

Task containing the call result
Type Parameters
Name Description
T

The Type returned by the protected function
TState

The Type of the state object passed into the protected function
| Edit this page View Source

WithCircuitBreaker<T, TState>(TState, Func<TState, Task<T>>)

Wraps invocation of asynchronous calls that need to be protected

Declaration
[Obsolete("Use WithCircuitBreaker() that accepts functions with CancellationToken parameter. Since 1.5.42")]
public Task<T> WithCircuitBreaker<T, TState>(TState state, Func<TState, Task<T>> body)
Parameters
Type Name Description
TState state

The state object will be passed into the protected function during invocation
Func<TState, Task<T>> body

Call needing protected
Returns
Type Description
Task<T>

Task containing the call result
Type Parameters
Name Description
T

The Type returned by the protected function
TState

The Type of the state object passed into the protected function
| Edit this page View Source

WithExponentialBackoff(TimeSpan)

The ResetTimeout will be increased exponentially for each failed attempt to close the circuit. The default exponential backoff factor is 2.

Declaration
public CircuitBreaker WithExponentialBackoff(TimeSpan maxResetTimeout)
Parameters
Type Name Description
TimeSpan maxResetTimeout

The upper bound of ResetTimeout
Returns
Type Description
CircuitBreaker
| Edit this page View Source

WithRandomFactor(double)

Adds jitter to the delay.

Declaration
public CircuitBreaker WithRandomFactor(double randomFactor)
Parameters
Type Name Description
double randomFactor

after calculation of the back-off an additional random delay based on this factor is added, e.g. 0.2 adds up to 20% delay. In order to skip this additional delay pass in 0.
Returns
Type Description
CircuitBreaker
| Edit this page View Source

WithSyncCircuitBreaker(Action)

Wraps invocations of asynchronous calls that need to be protected.

Declaration
public void WithSyncCircuitBreaker(Action body)
Parameters
Type Name Description
Action body

Call needing protected
| Edit this page View Source

WithSyncCircuitBreaker<T>(Func<T>)

Wraps invocations of asynchronous calls that need to be protected.

Declaration
public T WithSyncCircuitBreaker<T>(Func<T> body)
Parameters
Type Name Description
Func<T> body

Call needing protected
Returns
Type Description
T

The result of the call
Type Parameters
Name Description
T

The Type returned by the protected function

Extension Methods