Struct RetryPolicy 

pub struct RetryPolicy { /* private fields */ }

How many times to attempt an operation and how long to wait between tries.

max_attempts counts the total number of attempts, including the first one, so max_attempts = 1 means “try once, never retry” and max_attempts = 3 means “the first try plus up to two retries”. A value of 0 is rejected by new.

The Backoff supplies the delay before each retry. It is consulted only for delay values; the attempt count is governed solely by max_attempts, so the two limits never fight. If the backoff yields no delay for a given retry index, Duration::ZERO is used.

Implementations

impl RetryPolicy

pub const fn new(max_attempts: u32, backoff: Backoff) -> Option<Self>

Creates a policy that makes at most max_attempts attempts, waiting according to backoff between them.

Returns None if max_attempts is 0, which would never run the operation at all.

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:?}");
}

examples/basic_retry.rs (lines 18-21)

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 single(backoff: Backoff) -> Self

A policy that tries exactly once and never retries.

Equivalent to RetryPolicy::new(1, _).unwrap(); the backoff is never consulted because there is no retry.

pub const fn max_attempts(&self) -> u32

The maximum number of attempts (always >= 1).

pub const fn backoff(&self) -> &Backoff

The backoff schedule used between attempts.

pub fn delay_before_retry(&self, completed_attempts: u32) -> Duration

The delay to wait before the next retry, given how many attempts have already completed.

completed_attempts is the 1-based number of attempts already made, so the delay before the first retry is delay_before_retry(1). The backoff is indexed zero-based (retry 0 is the first retry); if it yields no delay, Duration::ZERO is returned.

Trait Implementations

impl Clone for RetryPolicy

fn clone(&self) -> RetryPolicy

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for RetryPolicy

impl Debug for RetryPolicy

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

Formats the value using the given formatter.