RetryPolicy<T> Class

Namespace
Kampute.Resilience
Assembly
  • Kampute.Resilience.dll

Definition

Represents a retry policy for operations returning T: a strategy that decides whether and when to retry, the exceptions and results that are retried, and callbacks for each retry.
public sealed class RetryPolicy<T>
Inheritance

Type Parameters

T
The type returned by the operations the policy runs.

Remarks

Create this policy with RetryPolicy.RetryOnResult<T>(Func<T, bool>) or RetryOnResult<T>(this IRetryStrategy, Func<T, bool>). Like RetryPolicy, it is immutable: each configuration method returns a new policy, and a policy can be shared by concurrent executions.

When the strategy allows no more retries after a retried result, execution returns that result. Results that execution does not return are passed to the handlers registered with OnDiscarded(Action<T>); the result that execution returns remains the caller's.

Callbacks run on the execution path. If an exception classifier throws, the operation's exception propagates as if it was not retried; an exception from a result classifier, delay override, retry handler, or discard handler propagates in place of the operation's outcome, and the operation is not retried.

Properties

Strategy

Gets the strategy of this policy.
public IRetryStrategy Strategy { get; }

Property Value

IRetryStrategy
The IRetryStrategy that decides whether and when to retry.

Methods

Execute(Func<CancellationToken, T>, CancellationToken)

Runs a blocking operation and retries it as this policy decides when it fails or returns a retried result.
public T Execute(Func<CancellationToken, T> operation, CancellationToken cancellationToken = default)

Parameters

operation Func<CancellationToken, T>
The operation to run. It receives cancellationToken.
cancellationToken CancellationToken optional
A token for canceling the operation and the waits between attempts (optional).

Returns

T
The first result that is not retried, or the last result when the strategy allows no more retries.

Exceptions

ArgumentNullException
Thrown if operation is null.
OperationCanceledException
Thrown if cancellationToken is canceled while waiting before a retry.

Remarks

The calling thread is blocked during the waits between attempts. When an exception is not retried, or the strategy allows no more retries, the last exception is rethrown with its original stack trace.

Execute<TState>(TState, Func<TState, CancellationToken, T>, CancellationToken)

Runs a blocking operation that receives a state, and retries it as this policy decides when it fails or returns a retried result.
public T Execute<TState>(TState state, Func<TState, CancellationToken, T> operation, CancellationToken cancellationToken = default)

Type Parameters

TState
The type of the state passed to the operation.

Parameters

state TState
The state passed to every attempt of the operation.
operation Func<TState, CancellationToken, T>
The operation to run. It receives state and cancellationToken.
cancellationToken CancellationToken optional
A token for canceling the operation and the waits between attempts (optional).

Returns

T
The first result that is not retried, or the last result when the strategy allows no more retries.

Exceptions

ArgumentNullException
Thrown if operation is null.
OperationCanceledException
Thrown if cancellationToken is canceled while waiting before a retry.

Remarks

The calling thread is blocked during the waits between attempts. When an exception is not retried, or the strategy allows no more retries, the last exception is rethrown with its original stack trace.

Pass the values that the operation needs as state and use an operation that captures no variables, such as a static lambda; the compiler then reuses one delegate instance, so the call allocates no closure. Use a tuple to pass several values.

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

Runs an asynchronous operation and retries it as this policy decides when it fails or returns a retried result.
public Task<T> ExecuteAsync(Func<CancellationToken, Task<T>> operation, CancellationToken cancellationToken = default)

Parameters

operation Func<CancellationToken, Task<T>>
The operation to run. It receives cancellationToken.
cancellationToken CancellationToken optional
A token for canceling the operation and the waits between attempts (optional).

Returns

Task<T>
A task that resolves to the first result that is not retried, or the last result when the strategy allows no more retries.

Exceptions

ArgumentNullException
Thrown, before a task is returned, if operation is null.
OperationCanceledException
Thrown if cancellationToken is canceled while waiting before a retry.

Remarks

When an exception is not retried, or the strategy allows no more retries, the last exception is rethrown with its original stack trace.

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

Runs an asynchronous operation that receives a state, and retries it as this policy decides when it fails or returns a retried result.
public Task<T> ExecuteAsync<TState>(TState state, Func<TState, CancellationToken, Task<T>> operation, CancellationToken cancellationToken = default)

Type Parameters

TState
The type of the state passed to the operation.

Parameters

state TState
The state passed to every attempt of the operation.
operation Func<TState, CancellationToken, Task<T>>
The operation to run. It receives state and cancellationToken.
cancellationToken CancellationToken optional
A token for canceling the operation and the waits between attempts (optional).

Returns

Task<T>
A task that resolves to the first result that is not retried, or the last result when the strategy allows no more retries.

Exceptions

ArgumentNullException
Thrown, before a task is returned, if operation is null.
OperationCanceledException
Thrown if cancellationToken is canceled while waiting before a retry.

Remarks

When an exception is not retried, or the strategy allows no more retries, the last exception is rethrown with its original stack trace.

Pass the values that the operation needs as state and use an operation that captures no variables, such as a static lambda; the compiler then reuses one delegate instance, so the call allocates no closure. Use a tuple to pass several values.

OnDiscarded(Action<T>)

Creates a policy that invokes a handler for each result that execution does not return, such as to release its resources.
public RetryPolicy<T> OnDiscarded(Action<T> handler)

Parameters

handler Action<T>
The handler, which receives the discarded result.

Returns

RetryPolicy<T>
A new policy that invokes the discard handlers of this policy and then handler.

Exceptions

ArgumentNullException
Thrown if handler is null.

Remarks

A retried result is discarded once: after the retry handlers and before the wait, or when a result classifier, delay override, retry handler, or wait fails. A result that is not retried, and the last result returned when the strategy allows no more retries, are not discarded and remain the caller's.

If a handler throws, later handlers do not run, and its exception propagates in place of any earlier callback or wait exception.

OnRetry(Action<RetryContext<T>>)

Creates a policy that invokes a handler for each approved retry.
public RetryPolicy<T> OnRetry(Action<RetryContext<T>> handler)

Parameters

handler Action<RetryContext<T>>
The handler, which receives the failed attempt and the delay that execution waits before the retry.

Returns

RetryPolicy<T>
A new policy that invokes the handlers of this policy and then handler.

Exceptions

ArgumentNullException
Thrown if handler is null.

Remarks

Handlers run before the wait, and only when a retry follows: not when the strategy allows no more retries, and not for outcomes that are not retried. For a retried result, they run before the discard handlers. If a handler throws, later handlers do not run.

OverrideDelay(Func<RetryContext<T>, TimeSpan>)

Creates a policy that replaces the strategy's delay with one computed from the failed attempt.
public RetryPolicy<T> OverrideDelay(Func<RetryContext<T>, TimeSpan> delay)

Parameters

delay Func<RetryContext<T>, TimeSpan>
A function that receives the failed attempt, whose RetryContext<T>.Delay is the delay that the strategy proposes, and returns the nonnegative delay to wait. Return RetryContext<T>.Delay to keep the proposed delay.

Returns

RetryPolicy<T>
A new policy whose delays delay selects. It replaces any delay override of this policy.

Exceptions

ArgumentNullException
Thrown if delay is null.

Remarks

The override runs only after the strategy allows a retry, and its delay replaces the proposed delay after all strategy modifiers, so it can exceed a delay cap or the time left under an elapsed-time limit. Enforce any required deadline in the override or with the caller's cancellation token.

A negative delay throws ArgumentOutOfRangeException from the execution, without a retry. A delay longer than int.MaxValue milliseconds stops retrying, as when the strategy allows no more retries.

RetryOn(Func<Exception, bool>)

Creates a policy that also retries the exceptions that satisfy a condition.
public RetryPolicy<T> RetryOn(Func<Exception, bool> predicate)

Parameters

predicate Func<Exception, bool>
A function that returns true for the exceptions to retry.

Returns

RetryPolicy<T>
A new policy that retries the exceptions this policy retries and the exceptions that predicate selects.

Exceptions

ArgumentNullException
Thrown if predicate is null.

Remarks

The first RetryOn call limits retries to the exceptions it selects; later calls add to them. If predicate throws, the operation's exception propagates without a retry.

RetryOn<TException>()

Creates a policy that also retries exceptions of the specified type.
public RetryPolicy<T> RetryOn<TException>()
	where TException : Exception

Type Parameters

TException
The type of the exceptions to retry, including derived types.

Returns

RetryPolicy<T>
A new policy that retries the exceptions this policy retries and the exceptions of type TException.

Remarks

The first RetryOn call limits retries to the exceptions it selects; later calls add to them.

RetryOn<TException>(Func<TException, bool>)

Creates a policy that also retries exceptions of the specified type that satisfy a condition.
public RetryPolicy<T> RetryOn<TException>(Func<TException, bool> predicate)
	where TException : Exception

Type Parameters

TException
The type of the exceptions to retry, including derived types.

Parameters

predicate Func<TException, bool>
A function that returns true for the exceptions of type TException to retry.

Returns

RetryPolicy<T>
A new policy that retries the exceptions this policy retries and the exceptions that predicate selects.

Exceptions

ArgumentNullException
Thrown if predicate is null.

Remarks

The first RetryOn call limits retries to the exceptions it selects; later calls add to them. If predicate throws, the operation's exception propagates without a retry.

RetryOnResult(Func<T, bool>)

Creates a policy that also retries the results that satisfy a condition.
public RetryPolicy<T> RetryOnResult(Func<T, bool> predicate)

Parameters

predicate Func<T, bool>
A function that returns true for the results to retry.

Returns

RetryPolicy<T>
A new policy that retries the results this policy retries and the results that predicate selects.

Exceptions

ArgumentNullException
Thrown if predicate is null.