Class CircuitBreakerOptions

Namespace

Kevlar

Assembly

Kevlar.dll

Configuration for a circuit breaker strategy. Configure either ConsecutiveFailures (simple mode) or FailureRatio (sampling mode). When neither is set, the breaker trips after 5 consecutive failures.

public sealed class CircuitBreakerOptions

Inheritance

object

CircuitBreakerOptions

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

CircuitBreakerOptions()

public CircuitBreakerOptions()

Properties

BreakDuration

How long the circuit stays open before allowing a probe. Default 15 seconds.

public TimeSpan BreakDuration { get; set; }

Property Value

TimeSpan

BreakDurationGenerator

Produces the break duration when a handled or slow outcome trips or re-opens the circuit, and is awaited before the circuit opens. The returned value must be positive. Return new(duration) from a synchronous generator. The event context is valid only until the returned task completes. When configured, this value overrides BreakDuration.

public Func<CircuitBreakerBreakDurationEvent, ValueTask<TimeSpan>>? BreakDurationGenerator { get; set; }

Property Value

Func<CircuitBreakerBreakDurationEvent, ValueTask<TimeSpan>>

ConsecutiveFailures

Trips the circuit after this many consecutive handled failures.

public int? ConsecutiveFailures { get; set; }

Property Value

int?

FailureRatio

Trips the circuit when the ratio of handled failures within SamplingWindow reaches this value (0 to 1), provided at least MinimumThroughput executions were observed in the window.

public double? FailureRatio { get; set; }

Property Value

double?

HalfOpenProbes

Number of completed probes used to evaluate one half-open cohort. Default 1.

public int HalfOpenProbes { get; set; }

Property Value

int

Remarks

At most this many probes run concurrently. Simple mode reopens on the first handled failure; ratio mode compares failed probes against this cohort size. The circuit closes after the whole cohort completes below the configured thresholds. Unhandled or cancelled probes release their slot.

HandlesException

Setting this — or, on CircuitBreakerOptions<TResult>, its HandlesResult — makes this circuit breaker ignore the ambient When… handling clause; this predicate then selects the exceptions it handles.

public Func<Exception, bool>? HandlesException { get; set; }

Property Value

Func<Exception, bool>

Remarks

The ambient clause is started with When… on a shield and continued with Or… on the builder it returns, and applies to every reactive strategy chained after it. These properties replace that clause for this strategy alone; they do not narrow it.

See Also

HandlingClause

HandlesExceptionContext

Locally handles exceptions using execution context and strategy metadata.

public Func<HandlingEvent, bool>? HandlesExceptionContext { get; set; }

Property Value

Func<HandlingEvent, bool>

MinimumThroughput

Minimum executions in the sampling window before FailureRatio can trip the circuit. Default 10.

public int MinimumThroughput { get; set; }

Property Value

int

Monitor

An optional monitor giving external code visibility of the circuit state plus manual Isolate() / Reset() control. A monitor can be bound to only one circuit breaker.

public CircuitBreakerMonitor? Monitor { get; set; }

Property Value

CircuitBreakerMonitor

Name

An optional low-cardinality name used by strategy telemetry.

public string? Name { get; set; }

Property Value

string

OnStateChanged

Invoked and awaited on every state transition, before StateChanged. Transitions are delivered serially outside the circuit lock, so a slow handler delays later transition publishers. Return default from a synchronous callback. The event context is valid only until the returned task completes. A non-reentrant publisher arriving during an active drain waits for the earlier handlers; an execution may therefore occupy a thread-pool thread until they return. A publisher reentered from OnStateChanged or StateChanged is queued and returns before the queued transition's observers run.

public Func<CircuitBreakerStateChangedEvent, ValueTask>? OnStateChanged { get; set; }

Property Value

Func<CircuitBreakerStateChangedEvent, ValueTask>

SamplingWindow

The rolling window over which the failure ratio is measured. Default 30 seconds.

public TimeSpan SamplingWindow { get; set; }

Property Value

TimeSpan

SlowCallRatio

Opens the circuit when this fraction of sampled calls is slow, independently of the handled failure ratio.

public double? SlowCallRatio { get; set; }

Property Value

double?

Remarks

Requires SlowCallThreshold and FailureRatio; uses the same sampling window and minimum throughput. In half-open state, the denominator is HalfOpenProbes. Valid values are greater than zero and at most one.

SlowCallThreshold

Successful or handled calls taking longer than this duration count toward SlowCallRatio.

public TimeSpan? SlowCallThreshold { get; set; }

Property Value

TimeSpan?

Remarks

Requires ratio mode and SlowCallRatio. Detection does not cancel work or change its result.