Struct ExponentialBackoffBuilder

pub struct ExponentialBackoffBuilder { /* private fields */ }

Builds an exponential backoff policy.

Example

use retry_policies::{RetryDecision, RetryPolicy, Jitter};
use retry_policies::policies::ExponentialBackoff;
use std::time::Duration;

let backoff = ExponentialBackoff::builder()
    .retry_bounds(Duration::from_secs(1), Duration::from_secs(60))
    .jitter(Jitter::Bounded)
    .base(2)
    .build_with_total_retry_duration(Duration::from_secs(24 * 60 * 60));

Implementations

impl ExponentialBackoffBuilder

pub fn retry_bounds( self, min_retry_interval: Duration, max_retry_interval: Duration, ) -> ExponentialBackoffBuilder

Add min & max retry interval bounds. Default [1s, 30m].

See ExponentialBackoff::min_retry_interval, ExponentialBackoff::max_retry_interval.

Panics if min_retry_interval > max_retry_interval.

pub fn jitter(self, jitter: Jitter) -> ExponentialBackoffBuilder

Set what type of jitter to apply.

pub fn base(self, base: u32) -> ExponentialBackoffBuilder

Set what base to use for the exponential.

pub fn build_with_max_retries(self, n: u32) -> ExponentialBackoff

Builds an ExponentialBackoff with the given maximum retries.

See ExponentialBackoff::max_n_retries.

pub fn build_with_total_retry_duration( self, total_duration: Duration, ) -> ExponentialBackoffTimed

Builds an ExponentialBackoff with the given maximum total duration for which retries will continue to be performed.

Example

use retry_policies::{RetryDecision, RetryPolicy};
use retry_policies::policies::ExponentialBackoff;
use std::time::{Duration, SystemTime};

let backoff = ExponentialBackoff::builder()
    .build_with_total_retry_duration(Duration::from_secs(24 * 60 * 60));

let started_at = SystemTime::now()
    .checked_sub(Duration::from_secs(25 * 60 * 60))
    .unwrap();

let should_retry = backoff.should_retry(started_at, 0);
assert!(matches!(RetryDecision::DoNotRetry, should_retry));

pub fn build_with_total_retry_duration_and_limit_retries( self, total_duration: Duration, ) -> ExponentialBackoffTimed

Builds an ExponentialBackoffTimed with the given maximum total duration and limits the number of retries to a calculated maximum.

This calculated maximum is based on how many attempts would be made without jitter applied.

For example if we set total duration 24 hours, with retry bounds [1s, 24h] and 2 as base of the exponential, we would calculate 17 max retries, as 1s * pow(2, 16) = 65536s = ~18 hours and 18th attempt would be way after the 24 hours total duration.

If the 17th retry ends up being scheduled after 10 hours due to jitter, ExponentialBackoff::should_retry will return false anyway: no retry will be allowed after total duration.

If one of the 17 allowed retries for some reason (e.g. previous attempts taking a long time) ends up being scheduled after total duration, ExponentialBackoff::should_retry will return false.

Basically we will enforce whatever comes first, max retries or total duration.

Example

use retry_policies::{RetryDecision, RetryPolicy};
use retry_policies::policies::ExponentialBackoff;
use std::time::{Duration, SystemTime};

let exponential_backoff_timed = ExponentialBackoff::builder()
    .retry_bounds(Duration::from_secs(1), Duration::from_secs(6 * 60 * 60))
    .build_with_total_retry_duration_and_limit_retries(Duration::from_secs(24 * 60 * 60));

assert_eq!(exponential_backoff_timed.max_retries(), Some(17));

let started_at = SystemTime::now()
    .checked_sub(Duration::from_secs(25 * 60 * 60))
    .unwrap();

let should_retry = exponential_backoff_timed.should_retry(started_at, 0);
assert!(matches!(RetryDecision::DoNotRetry, should_retry));

let started_at = SystemTime::now()
    .checked_sub(Duration::from_secs(1 * 60 * 60))
    .unwrap();

let should_retry = exponential_backoff_timed.should_retry(started_at, 18);
assert!(matches!(RetryDecision::DoNotRetry, should_retry));

pub fn build_with_total_retry_duration_and_max_retries( self, total_duration: Duration, max_n_retries: u32, ) -> ExponentialBackoffTimed

Builds an ExponentialBackoffTimed with the given maximum total duration and maximum retries.

Trait Implementations

impl Default for ExponentialBackoffBuilder

fn default() -> ExponentialBackoffBuilder

Returns the “default value” for a type.