Trait PolicyExt 

pub trait PolicyExt: BackoffPolicy + Sized {
    // Provided methods
    fn max_attempts(self, max: u32) -> MaxAttempts<Self> { ... }
    fn with_max_delay(self, max_delay: Duration) -> WithMaxDelay<Self> { ... }
    fn max_elapsed_time<C: Clock>(
        self,
        clock: C,
        max_elapsed: Duration,
    ) -> MaxElapsedTime<Self, C> { ... }
}

Ergonomic, zero-cost combinators for any BackoffPolicy.

Blanket-implemented for every policy, so you can fluently layer caps:

use core::time::Duration;
use sisyphus::{Constant, PolicyExt};

let policy = Constant::new(Duration::from_millis(100))
    .with_max_delay(Duration::from_secs(1))
    .max_attempts(3);

Provided Methods

fn max_attempts(self, max: u32) -> MaxAttempts<Self>

Cap the number of retries to max. See MaxAttempts.

This counts retries, not total attempts: the initial attempt is always made before any delay, so the operation runs up to max + 1 times.

Examples found in repository

examples/async_retry.rs (line 27)

async fn run() -> Result<u32, RetryError<&'static str>> {
    let policy = ExponentialBackoff::new(Duration::from_millis(10), 2.0).max_attempts(5);
    let mut attempt = 0u32;

    retry_async(
        policy,
        || {
            attempt += 1;
            async move {
                println!("async attempt {attempt}");
                if attempt < 4 {
                    ControlFlow::Continue("service unavailable")
                } else {
                    ControlFlow::Break(attempt)
                }
            }
        },
        // Swap this closure for your runtime's real sleep in production.
        fake_sleep,
    )
    .await
}

examples/quick_start.rs (line 28)

fn main() {
    let policy = ExponentialBackoff::new(Duration::from_millis(50), 2.0)
        .with_max_delay(Duration::from_secs(1))
        .max_attempts(6);

    let mut attempt = 0u32;
    let started = Instant::now();

    let result: Result<&str, RetryError<&str>> = retry_sync(
        policy,
        || {
            attempt += 1;
            match flaky_connect(attempt) {
                Ok(ok) => ControlFlow::Break(ok),
                Err(transient) => {
                    println!("attempt {attempt} failed: {transient}");
                    ControlFlow::Continue(transient)
                }
            }
        },
        // The execution side is entirely yours; here we block the OS thread.
        |delay| {
            println!("  backing off for {delay:?}");
            std::thread::sleep(delay);
        },
    );

    match result {
        Ok(msg) => println!(
            "success after {attempt} attempts in {:?}: {msg}",
            started.elapsed()
        ),
        Err(RetryError::Exhausted(last)) => {
            println!("gave up after {attempt} attempts; last error: {last}");
        }
    }
}

fn with_max_delay(self, max_delay: Duration) -> WithMaxDelay<Self>

Clamp every produced delay to at most max_delay. See WithMaxDelay.

Examples found in repository

examples/quick_start.rs (line 27)

fn main() {
    let policy = ExponentialBackoff::new(Duration::from_millis(50), 2.0)
        .with_max_delay(Duration::from_secs(1))
        .max_attempts(6);

    let mut attempt = 0u32;
    let started = Instant::now();

    let result: Result<&str, RetryError<&str>> = retry_sync(
        policy,
        || {
            attempt += 1;
            match flaky_connect(attempt) {
                Ok(ok) => ControlFlow::Break(ok),
                Err(transient) => {
                    println!("attempt {attempt} failed: {transient}");
                    ControlFlow::Continue(transient)
                }
            }
        },
        // The execution side is entirely yours; here we block the OS thread.
        |delay| {
            println!("  backing off for {delay:?}");
            std::thread::sleep(delay);
        },
    );

    match result {
        Ok(msg) => println!(
            "success after {attempt} attempts in {:?}: {msg}",
            started.elapsed()
        ),
        Err(RetryError::Exhausted(last)) => {
            println!("gave up after {attempt} attempts; last error: {last}");
        }
    }
}

fn max_elapsed_time<C: Clock>( self, clock: C, max_elapsed: Duration, ) -> MaxElapsedTime<Self, C>

Stop retrying after max_elapsed measured by clock. See MaxElapsedTime.

Examples found in repository

examples/system_clock.rs (line 18)

fn main() {
    // Poll every 20ms, but never spend more than 200ms of real time trying.
    let policy = Constant::new(Duration::from_millis(20))
        .max_elapsed_time(SystemClock, Duration::from_millis(200));

    let mut attempt = 0u32;
    let result: Result<(), RetryError<u32>> = retry_sync(
        policy,
        || {
            attempt += 1;
            ControlFlow::Continue(attempt) // never succeeds; rely on the budget
        },
        std::thread::sleep,
    );

    match result {
        Ok(()) => unreachable!(),
        Err(RetryError::Exhausted(last)) => {
            println!("real-time budget exhausted after {last} attempts");
        }
    }
}

examples/custom_clock.rs (line 52)

fn main() {
    let clock = VirtualClock::new();

    // Give up once 2 seconds of *virtual* time have elapsed.
    let policy = ExponentialBackoff::new(Duration::from_millis(100), 2.0)
        .max_elapsed_time(&clock, Duration::from_secs(2));

    let mut attempt = 0u32;
    let outcome: Result<(), RetryError<u32>> = retry_sync(
        policy,
        || {
            attempt += 1;
            // This operation never succeeds, so we lean on the time budget.
            ControlFlow::Continue(attempt)
        },
        // "Sleeping" just moves virtual time forward — no real waiting.
        |delay| {
            clock.advance(delay);
            println!("slept {delay:?}, virtual t = {}ms", clock.now());
        },
    );

    match outcome {
        Ok(()) => unreachable!("operation never breaks"),
        Err(RetryError::Exhausted(last)) => {
            println!(
                "budget exhausted after {last} attempts at virtual t = {}ms",
                clock.now()
            );
        }
    }
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<P: BackoffPolicy> PolicyExt for P