Class ExponentialBackOff
- All Implemented Interfaces:
BackOff
BackOff
that increases the back off period for each retry attempt using
a randomization function that grows exponentially.
nextBackOffMillis()
is calculated using the following formula:
randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])
In other words nextBackOffMillis()
will range between the randomization factor
percentage below and above the retry interval. For example, using 2 seconds as the base retry
interval and 0.5 as the randomization factor, the actual back off period used in the next retry
attempt will be between 1 and 3 seconds.
Note: max_interval caps the retry_interval and not the randomized_interval.
If the time elapsed since an ExponentialBackOff
instance is created goes past the
max_elapsed_time then the method nextBackOffMillis()
starts returning BackOff.STOP
. The elapsed time can be reset by calling reset()
.
Example: The default retry_interval is .5 seconds, default randomization_factor is 0.5, default multiplier is 1.5 and the default max_interval is 1 minute. For 10 tries the sequence will be (values in seconds) and assuming we go over the max_elapsed_time on the 10th try:
request# retry_interval randomized_interval
1 0.5 [0.25, 0.75]
2 0.75 [0.375, 1.125]
3 1.125 [0.562, 1.687]
4 1.687 [0.8435, 2.53]
5 2.53 [1.265, 3.795]
6 3.795 [1.897, 5.692]
7 5.692 [2.846, 8.538]
8 8.538 [4.269, 12.807]
9 12.807 [6.403, 19.210]
10 19.210 BackOff.STOP
Implementation is not thread-safe.
- Since:
- 1.15
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate int
The current retry interval in milliseconds.static final int
The default initial interval value in milliseconds (0.5 seconds).static final int
The default maximum elapsed time in milliseconds (15 minutes).static final int
The default maximum back off time in milliseconds (1 minute).static final double
The default multiplier value (1.5 which is 50% increase per back off).static final double
The default randomization factor (0.5 which results in a random period ranging between 50% below and 50% above the retry interval).private final int
The initial retry interval in milliseconds.private final int
The maximum elapsed time after instantiatingExponentialBackOff
or callingreset()
after whichnextBackOffMillis()
returnsBackOff.STOP
.private final int
The maximum value of the back off period in milliseconds.private final double
The value to multiply the current interval with for each retry attempt.private final NanoClock
Nano clock.private final double
The randomization factor to use for creating a range around the retry interval.(package private) long
The system time in nanoseconds.Fields inherited from interface com.google.api.client.util.BackOff
STOP, STOP_BACKOFF, ZERO_BACKOFF
-
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates an instance of ExponentialBackOffPolicy using default values.protected
-
Method Summary
Modifier and TypeMethodDescriptionfinal int
Returns the current retry interval in milliseconds.final long
Returns the elapsed time in milliseconds since anExponentialBackOff
instance is created and is reset whenreset()
is called.final int
Returns the initial retry interval in milliseconds.final int
Returns the maximum elapsed time in milliseconds.final int
Returns the maximum value of the back off period in milliseconds.final double
Returns the value to multiply the current interval with for each retry attempt.final double
Returns the randomization factor to use for creating a range around the retry interval.(package private) static int
getRandomValueFromInterval
(double randomizationFactor, double random, int currentIntervalMillis) Returns a random value from the interval [randomizationFactor * currentInterval, randomizationFactor * currentInterval].private void
Increments the current interval by multiplying it with the multiplier.long
Gets the number of milliseconds to wait before retrying the operation orBackOff.STOP
to indicate that no retries should be made.final void
reset()
Sets the interval back to the initial retry interval and restarts the timer.
-
Field Details
-
DEFAULT_INITIAL_INTERVAL_MILLIS
public static final int DEFAULT_INITIAL_INTERVAL_MILLISThe default initial interval value in milliseconds (0.5 seconds).- See Also:
-
DEFAULT_RANDOMIZATION_FACTOR
public static final double DEFAULT_RANDOMIZATION_FACTORThe default randomization factor (0.5 which results in a random period ranging between 50% below and 50% above the retry interval).- See Also:
-
DEFAULT_MULTIPLIER
public static final double DEFAULT_MULTIPLIERThe default multiplier value (1.5 which is 50% increase per back off).- See Also:
-
DEFAULT_MAX_INTERVAL_MILLIS
public static final int DEFAULT_MAX_INTERVAL_MILLISThe default maximum back off time in milliseconds (1 minute).- See Also:
-
DEFAULT_MAX_ELAPSED_TIME_MILLIS
public static final int DEFAULT_MAX_ELAPSED_TIME_MILLISThe default maximum elapsed time in milliseconds (15 minutes).- See Also:
-
currentIntervalMillis
private int currentIntervalMillisThe current retry interval in milliseconds. -
initialIntervalMillis
private final int initialIntervalMillisThe initial retry interval in milliseconds. -
randomizationFactor
private final double randomizationFactorThe randomization factor to use for creating a range around the retry interval.A randomization factor of 0.5 results in a random period ranging between 50% below and 50% above the retry interval.
-
multiplier
private final double multiplierThe value to multiply the current interval with for each retry attempt. -
maxIntervalMillis
private final int maxIntervalMillisThe maximum value of the back off period in milliseconds. Once the retry interval reaches this value it stops increasing. -
startTimeNanos
long startTimeNanosThe system time in nanoseconds. It is calculated when an ExponentialBackOffPolicy instance is created and is reset whenreset()
is called. -
maxElapsedTimeMillis
private final int maxElapsedTimeMillisThe maximum elapsed time after instantiatingExponentialBackOff
or callingreset()
after whichnextBackOffMillis()
returnsBackOff.STOP
. -
nanoClock
Nano clock.
-
-
Constructor Details
-
ExponentialBackOff
public ExponentialBackOff()Creates an instance of ExponentialBackOffPolicy using default values.To override the defaults use
ExponentialBackOff.Builder
.initialIntervalMillis
defaults toDEFAULT_INITIAL_INTERVAL_MILLIS
randomizationFactor
defaults toDEFAULT_RANDOMIZATION_FACTOR
multiplier
defaults toDEFAULT_MULTIPLIER
maxIntervalMillis
defaults toDEFAULT_MAX_INTERVAL_MILLIS
maxElapsedTimeMillis
defaults inDEFAULT_MAX_ELAPSED_TIME_MILLIS
-
ExponentialBackOff
- Parameters:
builder
- builder
-
-
Method Details
-
reset
public final void reset()Sets the interval back to the initial retry interval and restarts the timer. -
nextBackOffMillis
Gets the number of milliseconds to wait before retrying the operation orBackOff.STOP
to indicate that no retries should be made.Example usage:
long backOffMillis = backoff.nextBackOffMillis(); if (backOffMillis == Backoff.STOP) { // do not retry operation } else { // sleep for backOffMillis milliseconds and retry operation }
This method calculates the next back off interval using the formula: randomized_interval = retry_interval +/- (randomization_factor * retry_interval)
Subclasses may override if a different algorithm is required.
- Specified by:
nextBackOffMillis
in interfaceBackOff
- Throws:
IOException
-
getRandomValueFromInterval
static int getRandomValueFromInterval(double randomizationFactor, double random, int currentIntervalMillis) Returns a random value from the interval [randomizationFactor * currentInterval, randomizationFactor * currentInterval]. -
getInitialIntervalMillis
public final int getInitialIntervalMillis()Returns the initial retry interval in milliseconds. -
getRandomizationFactor
public final double getRandomizationFactor()Returns the randomization factor to use for creating a range around the retry interval.A randomization factor of 0.5 results in a random period ranging between 50% below and 50% above the retry interval.
-
getCurrentIntervalMillis
public final int getCurrentIntervalMillis()Returns the current retry interval in milliseconds. -
getMultiplier
public final double getMultiplier()Returns the value to multiply the current interval with for each retry attempt. -
getMaxIntervalMillis
public final int getMaxIntervalMillis()Returns the maximum value of the back off period in milliseconds. Once the current interval reaches this value it stops increasing. -
getMaxElapsedTimeMillis
public final int getMaxElapsedTimeMillis()Returns the maximum elapsed time in milliseconds.If the time elapsed since an
ExponentialBackOff
instance is created goes past the max_elapsed_time then the methodnextBackOffMillis()
starts returningBackOff.STOP
. The elapsed time can be reset by callingreset()
. -
getElapsedTimeMillis
public final long getElapsedTimeMillis()Returns the elapsed time in milliseconds since anExponentialBackOff
instance is created and is reset whenreset()
is called.The elapsed time is computed using
System.nanoTime()
. -
incrementCurrentInterval
private void incrementCurrentInterval()Increments the current interval by multiplying it with the multiplier.
-