Struct Backoff 

pub struct Backoff { /* private fields */ }

Re-exported from reliakit-backoff so the backoff schedule is reachable without a separate dependency line. A retry backoff policy.

Backoff is a small, Copy value. Construct one with Backoff::constant, Backoff::linear, or Backoff::exponential, then optionally cap it with Backoff::with_max_delay and Backoff::with_max_retries.

Backoff::delay takes a zero-based attempt number (attempt 0 is the wait before the first retry) and returns the delay, or None when the retry limit has been reached.

Implementations

impl Backoff

pub const fn constant(base: Duration) -> Backoff

A constant backoff that always waits base.

Examples found in repository

examples/async_retry.rs (line 30)

fn main() {
    let policy = RetryPolicy::new(4, Backoff::constant(Duration::from_millis(20)))
        .expect("max_attempts is non-zero");

    let mut attempt = 0;
    let result: Result<u32, RetryError<&str>> = block_on(retry_async(
        &policy,
        || {
            attempt += 1;
            let outcome = if attempt < 3 {
                Err("temporary")
            } else {
                Ok(200)
            };
            async move { outcome }
        },
        |_error| true,
        |delay| async move {
            // Your runtime's async sleep goes here. This example resolves
            // immediately; the sleep future is entirely user-provided.
            let _ = delay;
        },
    ));

    println!("async result after {attempt} attempt(s): {result:?}");
}

pub const fn linear(base: Duration, step: Duration) -> Backoff

A linear backoff: attempt n waits base + step * n.

pub const fn exponential(base: Duration, factor: u32) -> Backoff

An exponential backoff: attempt n waits base * factor^n.

factor is the integer multiplier (e.g. 2 doubles each attempt). A factor below 2 makes the policy behave like Backoff::constant.

Examples found in repository

examples/basic_retry.rs (line 20)

fn main() {
    let policy = RetryPolicy::new(
        5,
        Backoff::exponential(Duration::from_millis(50), 2).with_max_delay(Duration::from_secs(1)),
    )
    .expect("max_attempts is non-zero");

    // An operation that fails twice with a temporary error, then succeeds.
    let mut attempt = 0;
    let result: Result<&str, RetryError<ApiError>> = retry_with_sleep(
        &policy,
        || {
            attempt += 1;
            println!("attempt {attempt}");
            if attempt < 3 {
                Err(ApiError::Temporary)
            } else {
                Ok("payload")
            }
        },
        |error| matches!(error, ApiError::Temporary), // retry only temporary errors
        |delay| {
            // You provide the waiting. In real code, call your platform or
            // runtime sleep here; this example only reports the delay so it
            // stays dependency-free and instant.
            println!("  would wait {delay:?} before the next attempt");
        },
    );
    match result {
        Ok(body) => println!("succeeded with: {body}"),
        Err(error) => println!("gave up: {error:?}"),
    }

    // A fatal error stops immediately, even though attempts remain.
    let mut attempt = 0;
    let result: Result<&str, RetryError<ApiError>> = retry_with_sleep(
        &policy,
        || {
            attempt += 1;
            Err(ApiError::Fatal)
        },
        |error| matches!(error, ApiError::Temporary),
        |_delay| {},
    );
    println!(
        "fatal path: stopped after {} attempt(s)",
        result.unwrap_err().attempts()
    );
}

pub const fn with_max_delay(self, max_delay: Duration) -> Backoff

Caps every computed delay at max_delay.

Examples found in repository

examples/basic_retry.rs (line 20)

fn main() {
    let policy = RetryPolicy::new(
        5,
        Backoff::exponential(Duration::from_millis(50), 2).with_max_delay(Duration::from_secs(1)),
    )
    .expect("max_attempts is non-zero");

    // An operation that fails twice with a temporary error, then succeeds.
    let mut attempt = 0;
    let result: Result<&str, RetryError<ApiError>> = retry_with_sleep(
        &policy,
        || {
            attempt += 1;
            println!("attempt {attempt}");
            if attempt < 3 {
                Err(ApiError::Temporary)
            } else {
                Ok("payload")
            }
        },
        |error| matches!(error, ApiError::Temporary), // retry only temporary errors
        |delay| {
            // You provide the waiting. In real code, call your platform or
            // runtime sleep here; this example only reports the delay so it
            // stays dependency-free and instant.
            println!("  would wait {delay:?} before the next attempt");
        },
    );
    match result {
        Ok(body) => println!("succeeded with: {body}"),
        Err(error) => println!("gave up: {error:?}"),
    }

    // A fatal error stops immediately, even though attempts remain.
    let mut attempt = 0;
    let result: Result<&str, RetryError<ApiError>> = retry_with_sleep(
        &policy,
        || {
            attempt += 1;
            Err(ApiError::Fatal)
        },
        |error| matches!(error, ApiError::Temporary),
        |_delay| {},
    );
    println!(
        "fatal path: stopped after {} attempt(s)",
        result.unwrap_err().attempts()
    );
}

pub const fn with_max_retries(self, max_retries: u32) -> Backoff

Limits the policy to at most max_retries retries.

After this, delay returns None for attempt numbers >= max_retries.

pub const fn base(&self) -> Duration

Returns the base delay.

pub const fn max_delay(&self) -> Duration

Returns the maximum delay cap.

pub const fn max_retries(&self) -> Option<u32>

Returns the retry limit, if any.

pub fn delay(&self, attempt: u32) -> Option<Duration>

Returns the delay to wait before retry attempt (zero-based), or None if the retry limit has been reached.

The result is always clamped to max_delay. All arithmetic saturates and the computation runs in bounded time, so large attempt numbers never overflow, panic, or hang.

pub const fn delays(&self) -> Delays

Returns an iterator over the delays for attempts 0, 1, 2, ....

The iterator ends when the retry limit is reached. With no retry limit it is infinite.

Trait Implementations

impl Clone for Backoff

fn clone(&self) -> Backoff

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Backoff

impl Debug for Backoff

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for Backoff

impl Hash for Backoff

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Backoff

fn eq(&self, other: &Backoff) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Backoff