Class Strategy

Namespace

Kevlar

Assembly

Kevlar.dll

Base class for resilience strategies. A strategy is middleware: it receives a Continuation<T, TState> representing the rest of the pipeline and may invoke it zero, one or many times.

public abstract class Strategy

Inheritance

object

Strategy

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Implementations must be thread-safe: a single strategy instance is shared by every execution of the shield that contains it, and by every shield it is composed into. Strategy-local state (circuit breaker counters, rate limiter tokens, concurrency limit slots) is intentionally shared this way.

Strategies should communicate failures by returning FromException(Exception) rather than throwing, so that outer strategies can observe and handle them. Exceptions that do escape a strategy are converted to outcomes by the pipeline.

Constructors

Strategy()

protected Strategy()

Properties

Handling

The handling clause this reactive strategy acts on, or null for a proactive strategy. Override this when the strategy receives a clause through a Use factory so chain validation and testing descriptors can inspect it.

protected virtual HandlingClause? Handling { get; }

Property Value

HandlingClause?

InvokesContinuationAtMostOnce

Gets whether this strategy guarantees invoking its continuation at most once per execution.

protected virtual bool InvokesContinuationAtMostOnce { get; }

Property Value

bool

Remarks

Override and return true only when every path invokes next zero or one time. Strategies that retry, hedge, loop, or otherwise may invoke next more than once must retain the conservative default.

IsDuplicateReferenceUnsafe

Gets whether reusing this strategy instance within one chain is unsafe. Stateful custom strategies should override this property and return true when duplicate use could deadlock or corrupt their accounting.

protected virtual bool IsDuplicateReferenceUnsafe { get; }

Property Value

bool

SynchronousExecutionUnsupportedReason

Gets the configured feature that requires asynchronous execution, or null when this strategy supports synchronous execution.

protected virtual string? SynchronousExecutionUnsupportedReason { get; }

Property Value

string

Methods

Describe()

A one-line human-readable summary of this strategy and its configuration, used by ToString() to describe a whole pipeline. Defaults to the type name.

public virtual string Describe()

Returns

string

ExecuteAsync<T, TState>(Continuation<T, TState>, KevlarContext)

Executes the strategy around the rest of the pipeline.

public abstract ValueTask<Outcome<T>> ExecuteAsync<T, TState>(Continuation<T, TState> next, KevlarContext context)

Parameters

next Continuation<T, TState>

The remainder of the pipeline, ending in the user's delegate.

context KevlarContext

The ambient execution context.

Returns

ValueTask<Outcome<T>>

Type Parameters

T

The result type of the execution.

TState

Caller-supplied state threaded through the pipeline without allocation.

Remarks

Returning an incomplete value task during synchronous shield execution causes the execution boundary to block until it completes. Custom implementations should avoid capturing a single-threaded synchronization context and should be invoked asynchronously when they yield.

InvokeGenerator<TEvent, TResult>(Func<TEvent, ValueTask<TResult>>, TEvent, KevlarContext, string)

Invokes a generator hook whose result the strategy needs. Generator failures propagate to the caller. Under synchronous execution a generator that does not complete synchronously throws NotSupportedException.

protected static ValueTask<TResult> InvokeGenerator<TEvent, TResult>(Func<TEvent, ValueTask<TResult>> generator, TEvent callbackEvent, KevlarContext context, string hookName)

Parameters

generator Func<TEvent, ValueTask<TResult>>

The generator to invoke.

callbackEvent TEvent

The input passed to the generator.

context KevlarContext

The current execution context.

hookName string

The generator name used in synchronous-execution errors.

Returns

ValueTask<TResult>

The generator invocation.

Type Parameters

TEvent

The generator input type.

TResult

The generated result type.