Crate backon

Make retry like a built-in feature provided by Rust.

• Simple: Just like a built-in feature: your_fn.retry(ExponentialBuilder::default()).await.
• Flexible: Supports both blocking and async functions.
• Powerful: Allows control over retry behavior such as when and notify.
• Customizable: Supports custom retry strategies like exponential, constant, etc.

Backoff

Retry in BackON requires a backoff strategy. BackON will accept a BackoffBuilder which will generate a new Backoff for each retry.

BackON provides several backoff implementations with reasonable defaults:

• ConstantBuilder: backoff with a constant delay, limited to a specific number of attempts.
• ExponentialBuilder: backoff with an exponential delay, also supports jitter.
• FibonacciBuilder: backoff with a fibonacci delay, also supports jitter.

Sleep

Retry in BackON requires an implementation for sleeping. BackON will accept a Sleeper to pause for a specified duration.

BackON employs the following default sleep implementations:

• tokio-sleep: Utilizes TokioSleeper within a Tokio context in non-wasm32 environments.
• gloo-timers-sleep: Utilizes [GlooTimersSleep] to pause in wasm32 environments.

Users CAN provide a custom implementation if they prefer not to use the default options.

If neither feature is enabled nor a custom implementation is provided, BackON will fallback to an empty sleeper. This will cause a panic in the debug profile and do nothing in the release profile.

Retry

For additional examples, please visit docs::examples.

Retry an async function

use anyhow::Result;
use backon::ExponentialBuilder;
use backon::Retryable;
use core::time::Duration;

async fn fetch() -> Result<String> {
    Ok("hello, world!".to_string())
}

#[tokio::main]
async fn main() -> Result<()> {
    let content = fetch
        // Retry with exponential backoff
        .retry(ExponentialBuilder::default())
        // Sleep implementation, default to tokio::time::sleep if `tokio-sleep` has been enabled.
        .sleep(tokio::time::sleep)
        // When to retry
        .when(|e| e.to_string() == "EOF")
        // Notify when retrying
        .notify(|err: &anyhow::Error, dur: Duration| {
            println!("retrying {:?} after {:?}", err, dur);
        })
        .await?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

Retry a blocking function

use anyhow::Result;
use backon::BlockingRetryable;
use backon::ExponentialBuilder;
use core::time::Duration;

fn fetch() -> Result<String> {
    Ok("hello, world!".to_string())
}

fn main() -> Result<()> {
    let content = fetch
        // Retry with exponential backoff
        .retry(ExponentialBuilder::default())
        // When to retry
        .when(|e| e.to_string() == "EOF")
        // Notify when retrying
        .notify(|err: &anyhow::Error, dur: Duration| {
            println!("retrying {:?} after {:?}", err, dur);
        })
        .call()?;
    println!("fetch succeeded: {}", content);

    Ok(())
}

Re-exports

• pub use constant::ConstantBackoff;
• pub use fibonacci::FibonacciBackoff;
• pub use exponential::ExponentialBackoff;

Modules

• docsdocsrs
  Docs for the backon crate, like examples.

Structs

• BlockingRetry
  Retry structure generated by BlockingRetryable.
• BlockingRetryWithContext
  Retry structure generated by BlockingRetryableWithContext.
• ConstantBuilder
  ConstantBuilder is used to create a [ConstantBackoff], providing a steady delay with a fixed number of retries.
• ExponentialBuilder
  ExponentialBuilder is used to construct an [ExponentialBackoff] that offers delays with exponential retries.
• FibonacciBuilder
  FibonacciBuilder is used to build a [FibonacciBackoff] which offers a delay with Fibonacci-based retries.
• Retry
  Struct generated by Retryable.
• RetryWithContext
  Retry struct generated by RetryableWithContext.
• StdSleeperstd-blocking-sleep
  The implementation of StdSleeper uses std::thread::sleep.
• TokioSleeperNon-WebAssembly and tokio-sleep
  The default implementation of Sleeper uses tokio::time::sleep.

Traits

• Backoff
  Backoff is an Iterator that returns Duration.
• BackoffBuilder
  BackoffBuilder is utilized to construct a new backoff.
• BlockingRetryable
  BlockingRetryable adds retry support for blocking functions.
• BlockingRetryableWithContext
  BlockingRetryableWithContext adds retry support for blocking functions.
• BlockingSleeper
  A sleeper is used sleep for a specified duration.
• Retryable
  Retryable will add retry support for functions that produce futures with results.
• RetryableWithContext
  RetryableWithContext adds retry support for functions that produce futures with results and context.
• Sleeper
  A sleeper is used to generate a future that completes after a specified duration.

Type Aliases

• DefaultBlockingSleeper
  The default implementation of Sleeper while feature std-blocking-sleep enabled.
• DefaultSleeper
  The default implementation of Sleeper while feature tokio-sleep enabled.