Class RetrySettings (4.2.0)

public sealed class RetrySettings

Settings for retrying RPCs.

Inheritance

Object > RetrySettings

Namespace

Google.Api.Gax.Grpc

Assembly

Google.Api.Gax.Grpc.dll

Properties

BackoffJitter

public RetrySettings.IJitter BackoffJitter { get; }

The delay jitter to apply for delays, defaulting to RandomJitter. This is never null.

Property Value
TypeDescription
RetrySettings.IJitter
Remarks

"Jitter" is used to introduce randomness into the pattern of delays. This is to avoid multiple clients performing the same delay pattern starting at the same point in time, leading to higher-than-necessary contention. The default jitter simply takes each maximum delay and returns an actual delay which is a uniformly random value between 0 and the maximum. This is good enough for most applications, but makes precise testing difficult.

BackoffMultiplier

public double BackoffMultiplier { get; }

The multiplier to apply to the backoff on each iteration; always greater than or equal to 1.0.

Property Value
TypeDescription
Double
Remarks

As an example, a multiplier of 2.0 with an initial backoff of 0.1s on an RPC would then apply a backoff of 0.2s, then 0.4s until it is capped by MaxBackoff.

InitialBackoff

public TimeSpan InitialBackoff { get; }

The backoff time between the first attempt and the first retry. Always non-negative.

Property Value
TypeDescription
TimeSpan

MaxAttempts

public int MaxAttempts { get; }

The maximum number of attempts to make. Always greater than or equal to 1.

Property Value
TypeDescription
Int32

MaxBackoff

public TimeSpan MaxBackoff { get; }

The maximum backoff time between retries. Always non-negative.

Property Value
TypeDescription
TimeSpan

NoJitter

public static RetrySettings.IJitter NoJitter { get; }

A jitter which simply returns the specified maximum delay.

Property Value
TypeDescription
RetrySettings.IJitter

RandomJitter

public static RetrySettings.IJitter RandomJitter { get; }

The default jitter which returns a uniformly distributed random delay between 0 and the specified maximum.

Property Value
TypeDescription
RetrySettings.IJitter

RetryFilter

public Predicate<Exception> RetryFilter { get; }

A predicate to determine whether or not a particular exception should cause the operation to be retried. Usually this is simply a matter of checking the status codes. This is never null.

Property Value
TypeDescription
Predicate<Exception>

Methods

FilterForStatusCodes(StatusCode[])

public static Predicate<Exception> FilterForStatusCodes(params StatusCode[] statusCodes)

Creates a retry filter based on status codes.

Parameter
NameDescription
statusCodesStatusCode[]

The status codes to retry. Must not be null.

Returns
TypeDescription
Predicate<Exception>

A retry filter based on status codes.

FilterForStatusCodes(IEnumerable<StatusCode>)

public static Predicate<Exception> FilterForStatusCodes(IEnumerable<StatusCode> statusCodes)

Creates a retry filter based on status codes.

Parameter
NameDescription
statusCodesIEnumerable<StatusCode>

The status codes to retry. Must not be null.

Returns
TypeDescription
Predicate<Exception>

A retry filter based on status codes.

FromConstantBackoff(Int32, TimeSpan, Predicate<Exception>, RetrySettings.IJitter)

public static RetrySettings FromConstantBackoff(int maxAttempts, TimeSpan backoff, Predicate<Exception> retryFilter, RetrySettings.IJitter backoffJitter = null)

Returns a RetrySettings using the specified maximum number of attempts and a constant backoff. Jitter is still applied to each backoff, but the "base" value of the backoff is always backoff.

Parameters
NameDescription
maxAttemptsInt32

The maximum number of attempts to make. Must be positive.

backoffTimeSpan

The backoff after each failure. Must be non-negative.

retryFilterPredicate<Exception>

The predicate to use to check whether an error should be retried. Must not be null.

backoffJitterRetrySettings.IJitter

The jitter to use on each backoff. May be null, in which case RandomJitter is used.

Returns
TypeDescription
RetrySettings

A retry with constant backoff.

FromExponentialBackoff(Int32, TimeSpan, TimeSpan, Double, Predicate<Exception>, RetrySettings.IJitter)

public static RetrySettings FromExponentialBackoff(int maxAttempts, TimeSpan initialBackoff, TimeSpan maxBackoff, double backoffMultiplier, Predicate<Exception> retryFilter, RetrySettings.IJitter backoffJitter = null)

Returns a RetrySettings using the specified maximum number of attempts and an exponential backoff.

Parameters
NameDescription
maxAttemptsInt32

The maximum number of attempts to make. Must be positive.

initialBackoffTimeSpan

The backoff after the initial failure. Must be non-negative.

maxBackoffTimeSpan

The maximum backoff. Must be at least initialBackoff.

backoffMultiplierDouble

The multiplier to apply to backoff times. Must be at least 1.0.

retryFilterPredicate<Exception>

The predicate to use to check whether an error should be retried. Must not be null.

backoffJitterRetrySettings.IJitter

The jitter to use on each backoff. May be null, in which case RandomJitter is used.

Returns
TypeDescription
RetrySettings

A retry with exponential backoff.

NextBackoff(TimeSpan)

public TimeSpan NextBackoff(TimeSpan currentBackoff)

Works out the next backoff from the current one, based on the multiplier and maximum.

Parameter
NameDescription
currentBackoffTimeSpan

The current backoff to use as a basis for the next one.

Returns
TypeDescription
TimeSpan

The next backoff to use, which is always at least InitialBackoff and at most MaxBackoff.