Table of Contents

Class RetryPolicy

Namespace
Quartz
Assembly
Quartz.dll

How often, and how far apart, the scheduler re-fires a trigger whose job has failed.

public sealed class RetryPolicy : IEquatable<RetryPolicy>
Inheritance
RetryPolicy
Implements
Inherited Members

Remarks

A policy is a value: two policies of the same shape that would produce the same waits are equal. There is no public constructor — Fixed(int, TimeSpan), Exponential(int, TimeSpan, double, TimeSpan?) and Explicit(params IReadOnlyList<TimeSpan>) are the only ways to make one, so a policy that could not be honoured (no attempts, a negative wait, a backoff that shrinks) cannot be built at all.

MaxAttempts counts retries after the first failure, not fires: a trigger carrying Fixed(2, …) whose job keeps throwing runs three times in total and is then back on its ordinary schedule.

A retry never displaces the trigger's own next occurrence. The scheduler drops a retry that would land at (or within a second of) the regular next fire time and lets the schedule win, so a policy whose waits are longer than the gap between occurrences quietly does nothing.

Properties

BackoffFactor

What each wait is multiplied by to get the next one. 1 means a fixed wait.

public double BackoffFactor { get; }

Property Value

double

Remarks

Persisted with the round-trip ("R") format and the invariant culture, so a policy written on one machine reads back bit for bit on another.

Delays

The explicit table of waits, longest-lived entry last; empty when the waits are computed from InitialDelay and BackoffFactor.

public ImmutableArray<TimeSpan> Delays { get; }

Property Value

ImmutableArray<TimeSpan>

Remarks

A table shorter than the number of attempts cannot happen — MaxAttempts is its length — but the last entry repeats for any attempt beyond it, so the property is safe to index through DelayFor(int) alone.

InitialDelay

The wait before the first retry. For an Explicit(params IReadOnlyList<TimeSpan>) policy this is the first entry of Delays.

public TimeSpan InitialDelay { get; }

Property Value

TimeSpan

MaxAttempts

How many times the scheduler retries after the first failure. Always at least one.

public int MaxAttempts { get; }

Property Value

int

Remarks

This is the authoritative count: an Explicit(params IReadOnlyList<TimeSpan>) policy's is the length of its delay table, and once the attempts are spent the trigger returns to its ordinary schedule rather than going into an error state.

MaxDelay

The ceiling every computed wait is clamped to, or null when the backoff grows unbounded.

public TimeSpan? MaxDelay { get; }

Property Value

TimeSpan?

Methods

DelayFor(int)

The wait before the given retry.

public TimeSpan DelayFor(int attempt)

Parameters

attempt int

Which retry to compute the wait for, counting from one: 1 is the wait after the first failure.

Returns

TimeSpan

The wait, clamped to MaxDelay when there is one. An attempt beyond MaxAttempts answers as the last one does rather than throwing, because the decision to stop retrying belongs to the scheduler and not to the arithmetic.

Remarks

A wait too long to be represented is not an error. The arithmetic saturates, and the scheduler treats a retry it cannot express an instant for the way it treats one that would land on top of the next occurrence: there is no room for it, so the occurrence settles and the trigger keeps its ordinary schedule. Capping the waits when a policy is built or parsed instead would refuse a stored form that ToStoredString() had just written, and would refuse a policy over attempts no trigger will reach.

Exceptions

ArgumentOutOfRangeException

attempt is less than one.

Equals(RetryPolicy?)

Whether the other policy has the same shape and would produce exactly the same waits, the same number of times.

public bool Equals(RetryPolicy? other)

Parameters

other RetryPolicy

The policy to compare with.

Returns

bool

true when the two policies are the same value.

Remarks

Written out by hand rather than left to a record: the delay table is a collection, and reference equality on it would make two policies built from the same numbers unequal — which the store contract tests compare through. The backoff factor is compared bit for bit, which is what round-tripping it through the "R" format guarantees and what "the same policy came back out of the column" means.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

Explicit(params IReadOnlyList<TimeSpan>)

A policy that waits the given amounts, in order. MaxAttempts is the number of waits given.

public static RetryPolicy Explicit(params IReadOnlyList<TimeSpan> delays)

Parameters

delays IReadOnlyList<TimeSpan>

The wait before each retry, none of them negative and at least one of them present.

Returns

RetryPolicy

Exceptions

ArgumentNullException

delays is null.

ArgumentException

delays is empty, holds a negative wait, or is long enough that the stored form would not fit the triggers table's 250-character retry policy column.

Exponential(int, TimeSpan, double, TimeSpan?)

A policy whose wait grows by a constant factor with every retry.

public static RetryPolicy Exponential(int maxAttempts, TimeSpan initialDelay, double factor = 2, TimeSpan? maxDelay = null)

Parameters

maxAttempts int

How many times to retry after the first failure; at least one.

initialDelay TimeSpan

The wait before the first retry; not negative.

factor double

What each wait is multiplied by to get the next one. At least 1, which makes the policy wait the same amount every time; a shrinking backoff is not a backoff.

maxDelay TimeSpan?

A ceiling for the computed waits, or null to let them grow unbounded. Not shorter than initialDelay, which a ceiling below the first wait would silently undo.

Returns

RetryPolicy

Remarks

A factor of 1 is legal and produces the same waits as Fixed(int, TimeSpan), but it is a different value: it says the trigger's author chose a backoff and set its rate to one, which is a thing to change rather than a fixed wait spelled the long way.

Exceptions

ArgumentOutOfRangeException

maxAttempts is less than one, initialDelay is negative, factor is less than one or is not a number, or maxDelay is shorter than initialDelay.

Fixed(int, TimeSpan)

A policy that waits the same amount of time before every retry.

public static RetryPolicy Fixed(int maxAttempts, TimeSpan delay)

Parameters

maxAttempts int

How many times to retry after the first failure; at least one.

delay TimeSpan

The wait before each retry; not negative.

Returns

RetryPolicy

Exceptions

ArgumentOutOfRangeException

maxAttempts is less than one, or delay is negative.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

Parse(string)

Rebuilds a policy from the string ToStoredString() produced.

public static RetryPolicy Parse(string value)

Parameters

value string

The stored form.

Returns

RetryPolicy

The policy.

Exceptions

ArgumentNullException

value is null.

FormatException

value is not a stored retry policy.

ToStoredString()

The policy as the triggers table holds it: a compact, culture-invariant string that starts with a marker naming the policy's shape.

public string ToStoredString()

Returns

string

The stored form. Two policies that are equal produce the same string, and Parse(string) turns that string back into an equal policy.

ToString()

The policy as the triggers table holds it, which is the whole of its state.

public override string ToString()

Returns

string

TryParse(string?, out RetryPolicy?)

Rebuilds a policy from the string ToStoredString() produced, answering whether the string was one.

public static bool TryParse(string? value, out RetryPolicy? policy)

Parameters

value string

The stored form, which may be null or blank.

policy RetryPolicy

The policy, or null when there was not one.

Returns

bool

true when value was a stored retry policy.

Remarks

A null or blank string answers false rather than throwing: that is what a trigger row with no retry policy reads as.

Operators

operator ==(RetryPolicy?, RetryPolicy?)

Whether two policies are the same value.

public static bool operator ==(RetryPolicy? left, RetryPolicy? right)

Parameters

left RetryPolicy

The first policy.

right RetryPolicy

The second policy.

Returns

bool

true when both are null or both are equal.

operator !=(RetryPolicy?, RetryPolicy?)

Whether two policies are different values.

public static bool operator !=(RetryPolicy? left, RetryPolicy? right)

Parameters

left RetryPolicy

The first policy.

right RetryPolicy

The second policy.

Returns

bool

true when the two are not the same value.

Edit this page