1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
//! backon intends to provide an opposite backoff implementation of the popular [backoff](https://docs.rs/backoff).
//!
//! - Newer: developed by Rust edition 2021 and latest stable.
//! - Cleaner: Iterator based abstraction, easy to use, customization friendly.
//! - Easier: Trait based implementations, works like a native function provided by closures.
//!
//! # Backoff
//!
//! Any types that implements `Iterator<Item = Duration>` can be used as backoff.
//!
//! backon also provides backoff implementations with reasonable defaults:
//!
//! - [`ConstantBackoff`]: backoff with constant delay and limited times.
//! - [`ExponentialBackoff`]: backoff with exponential delay, also provides jitter supports.
//! - [`FibonacciBackoff`]: backoff with fibonacci delay, also provides jitter supports.
//!
//! Internally, `tokio::time::sleep()` will be used to sleep between retries, therefore
//! it will respect [pausing/auto-advancing](https://docs.rs/tokio/latest/tokio/time/fn.pause.html)
//! tokio's Runtime semantics, if enabled.
//!
//! # Examples
//!
//! Retry with default settings.
//!
//! ```no_run
//! use anyhow::Result;
//! use backon::ExponentialBuilder;
//! use backon::Retryable;
//!
//! async fn fetch() -> Result<String> {
//! Ok(reqwest::get("https://www.rust-lang.org")
//! .await?
//! .text()
//! .await?)
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let content = fetch.retry(&ExponentialBuilder::default()).await?;
//!
//! println!("fetch succeeded: {}", content);
//! Ok(())
//! }
//! ```
//!
//! Retry with specify retryable error.
//!
//! ```no_run
//! use anyhow::Result;
//! use backon::ExponentialBuilder;
//! use backon::Retryable;
//!
//! async fn fetch() -> Result<String> {
//! Ok(reqwest::get("https://www.rust-lang.org")
//! .await?
//! .text()
//! .await?)
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let content = fetch
//! .retry(&ExponentialBuilder::default())
//! .when(|e| e.to_string() == "retryable")
//! .await?;
//!
//! println!("fetch succeeded: {}", content);
//! Ok(())
//! }
//! ```
//!
//! Retry functions with args.
//!
//! ```no_run
//! use anyhow::Result;
//! use backon::ExponentialBuilder;
//! use backon::Retryable;
//!
//! async fn fetch(url: &str) -> Result<String> {
//! Ok(reqwest::get(url).await?.text().await?)
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let content = (|| async { fetch("https://www.rust-lang.org").await })
//! .retry(&ExponentialBuilder::default())
//! .when(|e| e.to_string() == "retryable")
//! .await?;
//!
//! println!("fetch succeeded: {}", content);
//! Ok(())
//! }
//! ```
//!
//! Retry functions with receiver `&self`.
//!
//! ```no_run
//! use anyhow::Result;
//! use backon::ExponentialBuilder;
//! use backon::Retryable;
//!
//! struct Test;
//!
//! impl Test {
//! async fn fetch(&self, url: &str) -> Result<String> {
//! Ok(reqwest::get(url).await?.text().await?)
//! }
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let test = Test;
//! let content = (|| async { test.fetch("https://www.rust-lang.org").await })
//! .retry(&ExponentialBuilder::default())
//! .when(|e| e.to_string() == "retryable")
//! .await?;
//!
//! println!("fetch succeeded: {}", content);
//! Ok(())
//! }
//! ```
//!
//! Retry functions with receiver `&mut self`.
//!
//! ```no_run
//! use anyhow::Result;
//! use backon::ExponentialBuilder;
//! use backon::RetryableWithContext;
//!
//! struct Test;
//!
//! impl Test {
//! async fn fetch(&mut self, url: &str) -> Result<String> {
//! Ok(reqwest::get(url).await?.text().await?)
//! }
//! }
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<()> {
//! let test = Test;
//!
//! let (_, result) = (|mut v: Test| async {
//! let res = v.fetch("https://www.rust-lang.org").await;
//! // Return input context back.
//! (v, res)
//! })
//! .retry(&ExponentialBuilder::default())
//! // Passing context in.
//! .context(test)
//! .when(|e| e.to_string() == "retryable")
//! .await;
//!
//! println!("fetch succeeded: {}", result.unwrap());
//! Ok(())
//! }
//! ```
#![deny(missing_docs)]
#![deny(unused_qualifications)]
mod backoff;
pub use backoff::Backoff;
pub use backoff::BackoffBuilder;
mod constant;
pub use constant::ConstantBackoff;
pub use constant::ConstantBuilder;
mod exponential;
pub use exponential::ExponentialBackoff;
pub use exponential::ExponentialBuilder;
mod fibonacci;
pub use fibonacci::FibonacciBackoff;
pub use fibonacci::FibonacciBuilder;
mod retry;
pub use retry::Retry;
pub use retry::Retryable;
mod retry_with_context;
pub use retry_with_context::RetryableWithContext;
mod blocking_retry;
pub use blocking_retry::BlockingRetry;
pub use blocking_retry::BlockingRetryable;
mod blocking_retry_with_context;
pub use blocking_retry_with_context::BlockingRetryableWithContext;