Class RetrySettings (4.4.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
Type Description
RetrySettingsIJitter
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
Type Description
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
Type Description
TimeSpan

MaxAttempts

public int MaxAttempts { get; }

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

Property Value
Type Description
int

MaxBackoff

public TimeSpan MaxBackoff { get; }

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

Property Value
Type Description
TimeSpan

NoJitter

public static RetrySettings.IJitter NoJitter { get; }

A jitter which simply returns the specified maximum delay.

Property Value
Type Description
RetrySettingsIJitter

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
Type Description
RetrySettingsIJitter

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
Type Description
PredicateException

Methods

FilterForStatusCodes(params StatusCode[])

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

Creates a retry filter based on status codes.

Parameter
Name Description
statusCodes StatusCode

The status codes to retry. Must not be null.

Returns
Type Description
PredicateException

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
Name Description
statusCodes IEnumerableStatusCode

The status codes to retry. Must not be null.

Returns
Type Description
PredicateException

A retry filter based on status codes.

FromConstantBackoff(int, TimeSpan, Predicate<Exception>, 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
Name Description
maxAttempts int

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

backoff TimeSpan

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

retryFilter PredicateException

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

backoffJitter RetrySettingsIJitter

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

Returns
Type Description
RetrySettings

A retry with constant backoff.

FromExponentialBackoff(int, TimeSpan, TimeSpan, double, Predicate<Exception>, 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
Name Description
maxAttempts int

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

initialBackoff TimeSpan

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

maxBackoff TimeSpan

The maximum backoff. Must be at least initialBackoff.

backoffMultiplier double

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

retryFilter PredicateException

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

backoffJitter RetrySettingsIJitter

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

Returns
Type Description
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
Name Description
currentBackoff TimeSpan

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

Returns
Type Description
TimeSpan

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