### FibonacciBackoff Series Example Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Demonstrates the Fibonacci sequence generation for retry delays, starting with a specified initial value. ```rust let mut iter = FibonacciBackoff::from_millis(10); assert_eq!(iter.next(), Some(Duration::from_millis(10))); assert_eq!(iter.next(), Some(Duration::from_millis(10))); assert_eq!(iter.next(), Some(Duration::from_millis(20))); assert_eq!(iter.next(), Some(Duration::from_millis(30))); assert_eq!(iter.next(), Some(Duration::from_millis(50))); assert_eq!(iter.next(), Some(Duration::from_millis(80))); ``` -------------------------------- ### start Method Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html Initializes a new `Retry` future with the given retry strategy and action. This is the primary method for starting a retry operation. ```APIDOC ### impl Retry where I: Iterator, A: Action, #### pub fn start>( strategy: T, action: A, ) -> Self Source ``` -------------------------------- ### start Function Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html?search=std%3A%3Avec Starts a new retry operation with the given strategy and action. This is the recommended method for initiating retries. ```APIDOC ### impl Retry where I: Iterator, A: Action, Source #### pub fn start>( strategy: T, action: A, ) -> Self Source ``` -------------------------------- ### start Method Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Initializes a new `Retry` instance with the provided retry strategy and action. This is the primary method for creating a retry future. ```APIDOC ## Implementations§ Source§ ### impl Retry where I: Iterator, A: Action, Source #### pub fn start>( strategy: T, action: A, ) -> Self Source ``` -------------------------------- ### RetryIf::spawn Method (Deprecated) Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html?search=u32+-%3E+bool Deprecated method for starting a RetryIf future. Use `start()` instead. It was renamed to `start()` in version 0.3.2. ```rust pub fn spawn>( strategy: T, action: A, condition: C, ) -> Self ``` -------------------------------- ### Spawn Retry Operation (Deprecated) Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html Deprecated method for starting a retry operation. It has been renamed to `start()` and should not be used in new code. Use `start()` instead. ```rust pub fn spawn>( strategy: T, action: A, ) -> Self ``` -------------------------------- ### spawn Method (Deprecated) Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html Spawns a new `Retry` future. This method is deprecated and has been renamed to `start()`. ```APIDOC #### pub fn spawn>( strategy: T, action: A, ) -> Self 👎Deprecated since 0.3.2: renamed to `start()` ``` -------------------------------- ### RetryIf::start Method Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html?search=u32+-%3E+bool Starts a new RetryIf future with a given strategy, action, and condition. This is the primary method for initiating a retry operation. ```rust pub fn start>( strategy: T, action: A, condition: C, ) -> Self ``` -------------------------------- ### RetryIf::spawn (Deprecated) Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html Deprecated function, renamed to `start()`. Creates a new RetryIf future that drives multiple attempts at an action. ```APIDOC ## RetryIf::spawn ### Description Deprecated since 0.3.2: renamed to `start()`. Creates a new `RetryIf` future that drives multiple attempts at an action. ### Signature ```rust #[deprecated(since = "0.3.2", note = "renamed to `start()`")] pub fn spawn>(strategy: T, action: A, condition: C) -> Self ``` ### Type Parameters * `T`: An iterator that produces `Duration` items, representing the retry strategy. * `I`: The iterator type produced by `T`. * `A`: The type implementing the `Action` trait, representing the action to be performed. * `C`: The type implementing the `Condition` trait, which determines if a retry should occur based on the action's error. ### Parameters * `strategy`: An iterator that yields `Duration` values, defining the delays between retries. * `action`: The action to be executed, which must implement the `Action` trait. * `condition`: A condition that evaluates the error returned by the action to decide whether to retry. ``` -------------------------------- ### ExponentialBackoff Base 10 Example Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Demonstrates the default behavior of ExponentialBackoff, where delays increase by a factor of 10. ```rust let mut s = ExponentialBackoff::from_millis(10); assert_eq!(s.next(), Some(Duration::from_millis(10))); assert_eq!(s.next(), Some(Duration::from_millis(100))); assert_eq!(s.next(), Some(Duration::from_millis(1000))); ``` -------------------------------- ### ExponentialBackoff Strategy Example Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html Demonstrates the behavior of the ExponentialBackoff strategy, showing the sequence of durations it generates. This strategy is useful for retrying operations with increasing delays. ```rust #[test] fn returns_some_exponential() { let mut s = ExponentialBackoff::new(Duration::from_secs(1), 2); assert_eq!(s.next(), Some(Duration::from_secs(1))); assert_eq!(s.next(), Some(Duration::from_secs(2))); } ``` -------------------------------- ### Basic Retry Example with Exponential Backoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/index.html?search= Demonstrates how to set up and use the Retry future with an exponential backoff strategy and jitter. This is useful for handling transient errors in asynchronous operations. ```rust use tokio_retry::Retry; use tokio_retry::strategy::{ExponentialBackoff, jitter}; async fn action() -> Result { // do some real-world stuff here... Err(()) } let retry_strategy = ExponentialBackoff::from_millis(10) .map(jitter) // add jitter to delays .take(3); // limit to 3 retries let result = Retry::start(retry_strategy, action).await?; ``` -------------------------------- ### Retry::start Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Starts a retry process with a given strategy and an action. The action is repeatedly executed until it succeeds or the strategy is exhausted. ```APIDOC ## Retry::start ### Description Starts a retry process with a given strategy and an action. The action is repeatedly executed until it succeeds or the strategy is exhausted. ### Parameters - `retry_strategy`: An iterator that yields delays between retries. - `action`: An async function or closure that returns a `Result`. ### Returns A `Future` that resolves to the result of the `action`. ### Example ```rust use tokio_retry::Retry; use tokio_retry::strategy::{ExponentialBackoff, jitter}; async fn action() -> Result { // do some real-world stuff here... Err(()) } let retry_strategy = ExponentialBackoff::from_millis(10) .map(jitter) // add jitter to delays .take(3); // limit to 3 retries let result = Retry::start(retry_strategy, action).await?; ``` ``` -------------------------------- ### RetryIf::start Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html?search= Initializes a new RetryIf future with a given retry strategy, action, and condition. This is the recommended method for starting a retry operation. ```APIDOC ## RetryIf::start ### Description Initializes a new `RetryIf` future with a given retry strategy, action, and condition. Retries are only attempted if the `Error` returned by the future satisfies a given condition. ### Signature ```rust pub fn start>(strategy: T, action: A, condition: C) -> Self ``` ### Type Parameters * `T`: An iterator type that yields `Duration` items, representing the retry strategy. * `I`: The iterator type produced by `T`. * `A`: The type implementing the `Action` trait, representing the operation to be retried. * `C`: The type implementing the `Condition` trait, which takes the error type of `A` and returns a boolean indicating whether to retry. ### Parameters * `strategy`: An iterator that provides the durations to wait between retries. * `action`: The action to perform, which returns a `Result`. * `condition`: A condition function that determines if a retry should occur based on the action's error. ``` -------------------------------- ### ExponentialBackoff Base 2 Example Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Shows ExponentialBackoff with a base multiplier of 2, resulting in delays doubling each time. ```rust let mut s = ExponentialBackoff::from_millis(2); assert_eq!(s.next(), Some(Duration::from_millis(2))); assert_eq!(s.next(), Some(Duration::from_millis(4))); assert_eq!(s.next(), Some(Duration::from_millis(8))); ``` -------------------------------- ### RetryIf::spawn Method (Deprecated) Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html Deprecated method for initializing a RetryIf future. Use `start()` instead. It takes a retry strategy, an action, and a condition for retrying. ```rust pub fn spawn>(strategy: T, action: A, condition: C) -> Self ``` -------------------------------- ### RetryIf::start Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/lib.rs.html Starts a retry operation with a strategy, action, and a condition to determine if a retry should occur based on the error. ```APIDOC ## RetryIf::start ### Description Starts a retry operation with a strategy, action, and a condition to determine if a retry should occur based on the error. ### Method `RetryIf::start` ### Parameters - `strategy`: An iterator yielding `Duration` values, defining the retry delays. - `action`: The asynchronous action to perform, which must implement the `Action` trait. - `condition`: A condition function that takes a reference to the error and returns `true` if a retry should be attempted. ``` -------------------------------- ### FixedInterval Strategy Example Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html Illustrates the FixedInterval strategy, which produces a constant delay duration between retries. This is suitable for scenarios where a consistent delay is preferred. ```rust #[test] fn returns_some_fixed() { let mut s = FixedInterval::new(Duration::from_millis(123)); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); } ``` -------------------------------- ### Retry::start Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html?search= Constructs a new Retry future with the given retry strategy and action. This is the primary method for starting a retry operation. ```APIDOC ### impl Retry where I: Iterator, A: Action, Source #### pub fn start>( strategy: T, action: A, ) -> Self Source ``` -------------------------------- ### RetryIf::spawn Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html?search=std%3A%3Avec Deprecated function, renamed to `start()`. Creates a new `RetryIf` future. This future will repeatedly execute the provided `action` until it succeeds or the `strategy` is exhausted. Retries are only performed if the error returned by the action satisfies the `condition`. ```APIDOC ## RetryIf::spawn ### Description Deprecated function, renamed to `start()`. Creates a new `RetryIf` future. This future will repeatedly execute the provided `action` until it succeeds or the `strategy` is exhausted. Retries are only performed if the error returned by the action satisfies the `condition`. ### Signature ```rust #[deprecated(since = "0.3.2", note = "renamed to `start()`")] pub fn spawn>(strategy: T, action: A, condition: C) -> Self ``` ### Type Parameters * `T`: An iterator type that yields `Duration` values, representing the retry strategy. * `I`: The iterator type produced by `T`. * `A`: The type implementing the `Action` trait, representing the operation to be retried. * `C`: The type implementing the `Condition` trait, used to determine if a retry should occur based on the action's error. ### Parameters * `strategy`: An iterator that provides the durations to wait between retries. * `action`: The action to be executed and potentially retried. * `condition`: The condition to evaluate the error against for determining if a retry is warranted. ``` -------------------------------- ### Retry::start Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/lib.rs.html?search=std%3A%3Avec Starts a new retry operation with a given strategy and action. The strategy is an iterator yielding `Duration`s for delays between retries. The action is a future that will be executed. ```APIDOC ## Retry::start ### Description Starts a new retry operation with a given strategy and action. The strategy is an iterator yielding `Duration`s for delays between retries. The action is a future that will be executed. ### Method `Retry::start` ### Parameters - `strategy`: An iterator yielding `Duration`s, defining the delays between retries. - `action`: The asynchronous action (a `Future`) to be retried. ### Example ```rust,no_run use tokio_retry::Retry; use tokio_retry::strategy::{ExponentialBackoff, jitter}; async fn action() -> Result { // do some real-world stuff here... Err(()) } # #[tokio::main] # async fn main() -> Result<(), ()> { let retry_strategy = ExponentialBackoff::from_millis(10) .map(jitter) // add jitter to delays .take(3); // limit to 3 retries let result = Retry::start(retry_strategy, action).await?; # Ok(()) # } ``` ``` -------------------------------- ### Retry::start Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Starts a new retry operation with a given strategy and action. The strategy is an iterator that yields `Duration`s, and the action is a future that returns a `Result`. This method is the primary way to initiate a retryable operation. ```APIDOC ## Retry::start ### Description Starts a new retry operation with a given strategy and action. The strategy is an iterator that yields `Duration`s, and the action is a future that returns a `Result`. ### Method `Retry::start>(strategy: T, action: A) -> Self` ### Parameters * `strategy`: An iterator that yields `Duration`s, defining the delays between retries. * `action`: The asynchronous action (a `Future`) to be executed and potentially retried. ### Returns A `Retry` future that will drive the execution of the action with the specified retry strategy. ``` -------------------------------- ### Construct FibonacciBackoff from Milliseconds Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html Creates a new FibonacciBackoff strategy with a base delay specified in milliseconds. This is the starting point for configuring the retry behavior. ```rust pub const fn from_millis(millis: u64) -> Self ``` -------------------------------- ### Start Retry Operation Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html Initializes a new Retry future. Use this to begin a sequence of retries for a given action with a specified strategy. The strategy must be convertible into an iterator of Durations. ```rust pub fn start>( strategy: T, action: A, ) -> Self ``` -------------------------------- ### Create a stepped iterator from FibonacciBackoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search= Creates a new iterator that starts from the same point as the FibonacciBackoff iterator but steps by a given amount at each iteration. This is useful for skipping elements. ```rust fn step_by(self, step: usize) -> StepBy ``` -------------------------------- ### Nightly-only: Get next N elements from FibonacciBackoff iterator Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search= This is a nightly-only experimental API that advances the FibonacciBackoff iterator and returns an array containing the next `N` values. It returns a `Result` which can be an array of items or an error if the iterator could not produce enough items. ```rust fn next_chunk( &mut self, ) -> Result<[Self::Item; N], IntoIter> where Self: Sized, ``` -------------------------------- ### Any Trait Implementation Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.Retry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Provides a way to get the TypeId of any type that implements Any. ```rust fn type_id(&self) -> TypeId ``` -------------------------------- ### take Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html Creates an iterator that yields the first `n` elements. ```APIDOC ## fn take(self, n: usize) -> Take ### Description Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ### Parameters - `n`: The maximum number of elements to yield. ``` -------------------------------- ### Any Trait Implementation Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html?search=std%3A%3Avec Implements the Any trait for RetryIf, providing a way to get the TypeId of the struct. ```rust fn type_id(&self) -> TypeId ``` -------------------------------- ### enumerate Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=u32+-%3E+bool Creates an iterator that yields pairs of the current iteration count (starting from 0) and the element. ```APIDOC ## fn enumerate(self) -> Enumerate ### Description Creates an iterator which gives the current iteration count as well as the next value. ### Parameters None ``` -------------------------------- ### Type Conversion Methods Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html Documentation for methods related to type conversions, including `from`, `into`, `try_from`, and `try_into`. ```APIDOC ## fn from(t: T) -> T Returns the argument unchanged. ## fn into(self) -> U Calls `U::from(self)`. That is, this conversion is whatever the implementation of `From for U` chooses to do. ## fn try_from(value: U) -> Result>::Error> Performs the conversion. ## fn try_into(self) -> Result>::Error> Performs the conversion. ``` -------------------------------- ### FibonacciBackoff Series Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=std%3A%3Avec Tests the generation of the Fibonacci sequence for retry delays, starting with a base of 10 milliseconds. ```rust #[test] fn exp_returns_the_fibonacci_series_starting_at_10() { let mut iter = FibonacciBackoff::from_millis(10); assert_eq!(iter.next(), Some(Duration::from_millis(10))); assert_eq!(iter.next(), Some(Duration::from_millis(10))); assert_eq!(iter.next(), Some(Duration::from_millis(20))); assert_eq!(iter.next(), Some(Duration::from_millis(30))); assert_eq!(iter.next(), Some(Duration::from_millis(50))); assert_eq!(iter.next(), Some(Duration::from_millis(80))); } ``` -------------------------------- ### FibonacciBackoff: Factor for Seconds Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html Demonstrates using the `factor` method to scale FibonacciBackoff delays, converting milliseconds to seconds. ```rust #[test] fn fib_can_use_factor_to_get_seconds() { let factor = 1000; let mut s = FibonacciBackoff::from_millis(1).factor(factor); assert_eq!(s.next(), Some(Duration::from_secs(1))); } ``` -------------------------------- ### RetryIf::start Method Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/struct.RetryIf.html Initializes a new RetryIf future with a given retry strategy, action, and condition. This is the primary method for creating a retryable operation. ```rust pub fn start>(strategy: T, action: A, condition: C) -> Self ``` -------------------------------- ### FibonacciBackoff with Factor Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=std%3A%3Avec Demonstrates using a factor to scale FibonacciBackoff delays, converting milliseconds to seconds. ```rust #[test] fn fib_can_use_factor_to_get_seconds() { let factor = 1000; let mut s = FibonacciBackoff::from_millis(1).factor(factor); assert_eq!(s.next(), Some(Duration::from_secs(1))); assert_eq!(s.next(), Some(Duration::from_secs(1))); } ``` -------------------------------- ### Get the size hint for ExponentialBackoff iterator Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Returns the bounds on the remaining length of the iterator. This provides an estimate of how many more retry durations can be generated. ```rust fn size_hint(&self) -> (usize, Option) ``` -------------------------------- ### ExponentialBackoff::factor Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=u32+-%3E+bool Applies a multiplicative factor to the retry delay. For example, a factor of 1000 makes delays units of seconds. Defaults to 1. ```APIDOC ## ExponentialBackoff::factor ### Description A multiplicative factor that will be applied to the retry delay. For example, using a factor of `1000` will make each delay in units of seconds. Default factor is `1`. ### Signature ```rust pub const fn factor(self, factor: u64) -> Self ``` ``` -------------------------------- ### ExponentialBackoff with Factor Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=std%3A%3Avec Demonstrates using a factor to scale the delays in ExponentialBackoff, converting milliseconds to seconds. ```rust #[test] fn exp_can_use_factor_to_get_seconds() { let factor = 1000; let mut s = ExponentialBackoff::from_millis(2).factor(factor); assert_eq!(s.next(), Some(Duration::from_secs(2))); assert_eq!(s.next(), Some(Duration::from_secs(4))); assert_eq!(s.next(), Some(Duration::from_secs(8))); } ``` -------------------------------- ### take Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search=std%3A%3Avec Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ```APIDOC ## fn take(self, n: usize) -> Take ### Description Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ### Parameters - `n`: The number of elements to take. ``` -------------------------------- ### Take Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ```APIDOC ## fn take(self, n: usize) -> Take Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ``` -------------------------------- ### ExponentialBackoff::factor Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Sets a multiplicative factor for the retry delay. For example, a factor of 1000 makes delays units of seconds. Defaults to 1. ```rust pub const fn factor(mut self, factor: u64) -> Self { self.factor = factor; self } ``` -------------------------------- ### Get the last retry duration from ExponentialBackoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Consumes the iterator and returns the last retry duration. This can be useful for understanding the maximum delay that would have been generated. ```rust fn last(self) -> Option where Self: Sized, ``` -------------------------------- ### Get the next chunk of retry durations Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Advances the iterator and returns an array containing the next N retry Durations. This is a nightly-only experimental API. ```rust fn next_chunk( &mut self, ) -> Result<[Self::Item; N], IntoIter> where Self: Sized, ``` -------------------------------- ### Exponential Backoff Strategy Tests Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Tests for the ExponentialBackoff strategy, demonstrating its behavior with different initial values, base factors, and maximum delay settings. ```rust #[test] fn exp_returns_some_exponential_base_10() { let mut s = ExponentialBackoff::from_millis(10); assert_eq!(s.next(), Some(Duration::from_millis(10))); assert_eq!(s.next(), Some(Duration::from_millis(100))); assert_eq!(s.next(), Some(Duration::from_millis(1000))); } #[test] fn exp_returns_some_exponential_base_2() { let mut s = ExponentialBackoff::from_millis(2); assert_eq!(s.next(), Some(Duration::from_millis(2))); assert_eq!(s.next(), Some(Duration::from_millis(4))); assert_eq!(s.next(), Some(Duration::from_millis(8))); } #[test] fn exp_saturates_at_maximum_value() { let mut s = ExponentialBackoff::from_millis(u64::MAX - 1); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX - 1))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); } #[test] fn exp_can_use_factor_to_get_seconds() { let factor = 1000; let mut s = ExponentialBackoff::from_millis(2).factor(factor); assert_eq!(s.next(), Some(Duration::from_secs(2))); assert_eq!(s.next(), Some(Duration::from_secs(4))); assert_eq!(s.next(), Some(Duration::from_secs(8))); } #[test] fn exp_stops_increasing_at_max_delay() { let mut s = ExponentialBackoff::from_millis(2).max_delay(Duration::from_millis(4)); assert_eq!(s.next(), Some(Duration::from_millis(2))); assert_eq!(s.next(), Some(Duration::from_millis(4))); assert_eq!(s.next(), Some(Duration::from_millis(4))); } #[test] fn exp_returns_max_when_max_less_than_base() { let mut s = ExponentialBackoff::from_millis(20).max_delay(Duration::from_millis(10)); assert_eq!(s.next(), Some(Duration::from_millis(10))); assert_eq!(s.next(), Some(Duration::from_millis(10))); } ``` -------------------------------- ### partition Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search=std%3A%3Avec Consumes an iterator, creating two collections from it. ```APIDOC ## fn partition(self, f: F) -> (B, B) ### Description Consumes an iterator, creating two collections from it. ### Parameters - `f`: A closure that takes a reference to an item and returns a boolean, determining which partition the item belongs to. ### Type Parameters - `B`: The type of the collections, which must implement `Default` and `Extend`. ``` -------------------------------- ### Fixed Interval Retry Strategy Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search= Demonstrates the creation and usage of a fixed interval retry strategy. This strategy provides a constant delay between retries. ```rust impl Iterator for FixedInterval { type Item = Duration; fn next(&mut self) -> Option { Some(self.interval) } } #[test] fn returns_some_fixed() { let mut s = FixedInterval::new(Duration::from_millis(123)); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); } ``` -------------------------------- ### Retry::start Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/lib.rs.html?search=u32+-%3E+bool Initializes a new Retry future that will repeatedly attempt an action according to the provided retry strategy. The action will be retried if it returns an error, and the retry strategy will determine the delay between attempts. ```APIDOC ## Retry::start ### Description Initializes a new Retry future that will repeatedly attempt an action according to the provided retry strategy. The action will be retried if it returns an error, and the retry strategy will determine the delay between attempts. ### Method ```rust pub fn start>(strategy: T, action: A) -> Self ``` ### Parameters - **strategy**: An iterator yielding `Duration` values, defining the delays between retry attempts. - **action**: The asynchronous action to perform, which must implement the `Action` trait. ### Returns A `Retry` future that will drive the execution of the action with retries. ``` -------------------------------- ### Get the next retry duration from ExponentialBackoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Advances the iterator and returns the next retry Duration based on the exponential back-off strategy. Returns None when the iterator is exhausted. ```rust fn next(&mut self) -> Option ``` -------------------------------- ### Fixed Interval Retry Strategy Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Demonstrates the FixedInterval strategy, which always returns the same duration for retries. Useful for scenarios requiring consistent delays. ```rust impl Strategy for FixedInterval { fn next(&mut self) -> Option { Some(self.interval) } } ``` ```rust #[test] fn returns_some_fixed() { let mut s = FixedInterval::new(Duration::from_millis(123)); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); assert_eq!(s.next(), Some(Duration::from_millis(123))); } ``` -------------------------------- ### Get the nth retry duration from ExponentialBackoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Returns the nth retry duration from the iterator. This allows direct access to a specific retry delay without iterating through previous ones. ```rust fn nth(&mut self, n: usize) -> Option ``` -------------------------------- ### ExponentialBackoff::factor Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html Applies a multiplicative factor to the retry delay. This allows scaling the delays, for example, to have delays in units of seconds by using a factor of 1000. The default factor is 1. ```APIDOC ## pub const fn factor(self, factor: u64) -> Self A multiplicative factor that will be applied to the retry delay. For example, using a factor of `1000` will make each delay in units of seconds. Default factor is `1`. ``` -------------------------------- ### by_ref Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a “by reference” adapter for this instance of `Iterator`. ```APIDOC ## fn by_ref(&mut self) -> &mut Self ### Description Creates a “by reference” adapter for this instance of `Iterator`. ``` -------------------------------- ### product Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html Iterates over the entire iterator, multiplying all the elements. The element type must implement the `Product` trait. ```APIDOC ## fn product

(self) -> P ### Description Iterates over the entire iterator, multiplying all the elements. ### Signature ```rust fn product

(self) -> P where Self: Sized, P: Product, ``` ``` -------------------------------- ### partition Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Consumes an iterator, creating two collections based on a predicate. ```APIDOC ## fn partition(self, f: F) -> (B, B) ### Description Consumes an iterator, creating two collections from it. ### Parameters - `f`: A closure that takes a reference to an item and returns a boolean indicating which partition it belongs to. ``` -------------------------------- ### partition Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Consumes an iterator, creating two collections from it based on a predicate. ```APIDOC ## fn partition(self, f: F) -> (B, B) ### Description Consumes an iterator, creating two collections from it. ### Parameters - `f`: A closure that takes a reference to an item and returns `true` if the item belongs to the first collection, `false` otherwise. ### Type Parameters - `B`: The type of the collections, which must implement `Default` and `Extend`. ``` -------------------------------- ### product Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=u32+-%3E+bool Iterates over the entire iterator, multiplying all the elements. ```APIDOC ## product

### Description Iterates over the entire iterator, multiplying all the elements. ### Signature ```rust fn product

(self) -> P where Self: Sized, P: Product, ``` ``` -------------------------------- ### ExponentialBackoff Saturation at Max Value Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Illustrates how ExponentialBackoff saturates at `u64::MAX` when the calculated delay exceeds the maximum representable value. ```rust let mut s = ExponentialBackoff::from_millis(u64::MAX - 1); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX - 1))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); ``` -------------------------------- ### Clone ExponentialBackoff strategy from source Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search= Performs copy-assignment from a source ExponentialBackoff strategy to the current one. This allows efficient cloning. ```rust fn clone_from(&mut self, source: &Self) ``` -------------------------------- ### RetryIf::start Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/lib.rs.html?search=u32+-%3E+bool Initializes a new RetryIf future. This future attempts an action and retries it based on a strategy only if the returned error satisfies a given condition. This allows for more granular control over when retries occur. ```APIDOC ## RetryIf::start ### Description Initializes a new RetryIf future. This future attempts an action and retries it based on a strategy only if the returned error satisfies a given condition. This allows for more granular control over when retries occur. ### Method ```rust pub fn start>( strategy: T, action: A, condition: C, ) -> Self ``` ### Parameters - **strategy**: An iterator yielding `Duration` values, defining the delays between retry attempts. - **action**: The asynchronous action to perform, which must implement the `Action` trait. - **condition**: A condition (implementing `Condition`) that determines whether a retry should be attempted based on the error returned by the action. ### Returns A `RetryIf` future that will drive the execution of the action with conditional retries. ``` -------------------------------- ### FixedInterval Iterator step_by() Method Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html?search=std%3A%3Avec Creates a new iterator that steps by a specified amount. This can be used to sample the fixed intervals. ```rust fn step_by(self, step: usize) -> StepBy where Self: Sized, ``` -------------------------------- ### ExponentialBackoff Saturation Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=std%3A%3Avec Tests how ExponentialBackoff handles saturation at the maximum possible `u64` value. ```rust #[test] fn exp_saturates_at_maximum_value() { let mut s = ExponentialBackoff::from_millis(u64::MAX - 1); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX - 1))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); assert_eq!(s.next(), Some(Duration::from_millis(u64::MAX))); } ``` -------------------------------- ### ByRef Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html Creates a “by reference” adapter for this instance of `Iterator`. ```APIDOC ## fn by_ref(&mut self) -> &mut Self Creates a “by reference” adapter for this instance of `Iterator`. ``` -------------------------------- ### partial_cmp_by(self, other: I, partial_cmp: F) -> Option Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html?search= Lexicographically compares elements using a custom comparison function, with short-circuit evaluation. This is a nightly-only experimental API. ```APIDOC ## partial_cmp_by(self, other: I, partial_cmp: F) -> Option ### Description Lexicographically compares the elements of this `Iterator` with those of another with respect to the specified comparison function. ### Note This is a nightly-only experimental API. (`iter_order_by`) ### Signature ```rust fn partial_cmp_by(self, other: I, partial_cmp: F) -> Option where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, ::Item) -> Option, ``` ``` -------------------------------- ### Construct ExponentialBackoff from Milliseconds Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=u32+-%3E+bool Creates a new exponential back-off strategy using a base duration in milliseconds. The delay increases exponentially with the number of attempts. ```rust pub const fn from_millis(base: u64) -> Self ``` -------------------------------- ### MapWindows Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well. ```APIDOC ## fn map_windows(self, f: F) -> MapWindows Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well. ``` -------------------------------- ### ExponentialBackoff: Base 10 Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html Tests the ExponentialBackoff strategy with a base of 10, verifying the sequence of delays. ```rust #[test] fn exp_returns_some_exponential_base_10() { let mut s = ExponentialBackoff::from_millis(10); assert_eq!(s.next(), Some(Duration::from_millis(10))); assert_eq!(s.next(), Some(Duration::from_millis(100))); assert_eq!(s.next(), Some(Duration::from_millis(1000))); } ``` -------------------------------- ### inspect Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html?search=u32+-%3E+bool Does something with each element of an iterator, passing the value on. ```APIDOC ## inspect(self, f: F) -> Inspect ### Description Does something with each element of an iterator, passing the value on. ### Parameters #### Path Parameters - `f` (F): A closure that takes a reference to an item and performs an action. ### Type Parameters - `F`: The type of the closure. ``` -------------------------------- ### map_windows Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search=u32+-%3E+bool Calls a function for each contiguous window of size `N` and returns an iterator over the results. ```APIDOC ## fn map_windows(self, f: F) -> MapWindows ### Description Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well. ### Parameters - `f`: A closure that takes a slice of `N` items and returns a value `R`. ``` -------------------------------- ### Standard Iterator Methods for ExponentialBackoff Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Includes standard iterator methods like `count`, `nth`, `step_by`, `chain`, `zip`, `map`, `for_each`, and `filter` for ExponentialBackoff. ```rust fn count(self) -> usize where Self: Sized, ``` ```rust fn nth(&mut self, n: usize) -> Option ``` ```rust fn step_by(self, step: usize) -> StepBy where Self: Sized, ``` ```rust fn chain(self, other: U) -> Chain::IntoIter> where Self: Sized, U: IntoIterator, ``` ```rust fn zip(self, other: U) -> Zip::IntoIter> where Self: Sized, U: IntoIterator, ``` ```rust fn map(self, f: F) -> Map where Self: Sized, F: FnMut(Self::Item) -> B, ``` ```rust fn for_each(self, f: F) where Self: Sized, F: FnMut(Self::Item), ``` ```rust fn filter

(self, predicate: P) -> Filter where Self: Sized, P: FnMut(&Self::Item) -> bool, ``` -------------------------------- ### FibonacciBackoff Saturation at Max Value Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Shows how FibonacciBackoff saturates at `u64::MAX` when the calculated Fibonacci number exceeds the maximum representable value. ```rust let mut iter = FibonacciBackoff::from_millis(u64::MAX); assert_eq!(iter.next(), Some(Duration::from_millis(u64::MAX))); assert_eq!(iter.next(), Some(Duration::from_millis(u64::MAX))); ``` -------------------------------- ### FibonacciBackoff Strategy Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=u32+-%3E+bool Implements a retry strategy using the Fibonacci sequence for delays. Each delay is the sum of the two previous delays, offering a potentially more balanced approach than exponential back-off. Configuration options include base duration, factor, and maximum delay. ```rust use core::iter::Iterator; use core::time::Duration; /// A retry strategy driven by the fibonacci series. /// /// Each retry uses a delay which is the sum of the two previous delays. /// /// Depending on the problem at hand, a fibonacci retry strategy might /// perform better and lead to better throughput than the `ExponentialBackoff` /// strategy. /// /// See ["A Performance Comparison of Different Backoff Algorithms under Different Rebroadcast Probabilities for MANETs."](https://www.researchgate.net/profile/Saher-Manaseer/publication/255672213_A_Performance_Comparison_of_Different_Backoff_Algorithms_under_Different_Rebroadcast_Probabilities_for_MANETs/links/542d40220cf29bbc126d2378/A-Performance-Comparison-of-Different-Backoff-Algorithms-under-Different-Rebroadcast-Probabilities-for-MANETs.pdf) /// for more details. #[derive(Debug, Clone)] pub struct FibonacciBackoff { curr: u64, next: u64, factor: u64, max_delay: Option, } impl FibonacciBackoff { /// Constructs a new fibonacci back-off strategy, /// given a base duration in milliseconds. pub const fn from_millis(millis: u64) -> Self { Self { curr: millis, next: millis, factor: 1u64, max_delay: None, } } /// A multiplicative factor that will be applied to the retry delay. /// /// For example, using a factor of `1000` will make each delay in units of seconds. /// /// Default factor is `1`. pub const fn factor(mut self, factor: u64) -> Self { self.factor = factor; self } /// Apply a maximum delay. No retry delay will be longer than this `Duration`. pub const fn max_delay(mut self, duration: Duration) -> Self { self.max_delay = Some(duration); self } } impl Iterator for FibonacciBackoff { type Item = Duration; fn next(&mut self) -> Option { // set delay duration by applying factor let duration = if let Some(duration) = self.curr.checked_mul(self.factor) { Duration::from_millis(duration) } else { Duration::from_millis(u64::MAX) }; // check if we reached max delay if let Some(ref max_delay) = self.max_delay { if duration > *max_delay { return Some(*max_delay); } } if let Some(next_next) = self.curr.checked_add(self.next) { self.curr = self.next; self.next = next_next; } else { self.curr = self.next; self.next = u64::MAX; } Some(duration) } } ``` -------------------------------- ### product Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html?search=std%3A%3Avec Iterates over the entire iterator, multiplying all the elements. The result type `P` must implement the `Product` trait for the iterator's item type. ```APIDOC ## product ### Description Iterates over the entire iterator, multiplying all the elements. ### Method Signature `fn product

(self) -> P` ### Type Constraints - `Self: Sized` - `P: Product` ``` -------------------------------- ### Borrowing Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FibonacciBackoff.html Methods for borrowing data immutably and mutably. ```APIDOC ## fn borrow(&self) -> &T Immutably borrows from an owned value. ## fn borrow_mut(&mut self) -> &mut T Mutably borrows from an owned value. ``` -------------------------------- ### fn partial_cmp_by(self, other: I, partial_cmp: F) -> Option Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html?search=u32+-%3E+bool Lexicographically compares the elements of this Iterator with those of another with respect to the specified comparison function. This is a nightly-only experimental API. ```APIDOC ## fn partial_cmp_by(self, other: I, partial_cmp: F) -> Option ### Description Lexicographically compares the elements of this `Iterator` with those of another with respect to the specified comparison function. ### Note This is a nightly-only experimental API. (`iter_order_by`) ### Signature ```rust fn partial_cmp_by(self, other: I, partial_cmp: F) -> Option where Self: Sized, I: IntoIterator, F: FnMut(Self::Item, ::Item) -> Option, ``` ``` -------------------------------- ### ExponentialBackoff::from_millis Source: https://docs.rs/tokio-retry/0.3.2/src/tokio_retry/strategy.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Constructs a new exponential back-off strategy with a base duration in milliseconds. The delay is calculated by raising the base to the power of the number of past attempts. ```rust pub const fn from_millis(base: u64) -> Self { Self { current: base, base, factor: 1u64, max_delay: None, } } ``` -------------------------------- ### product Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.FixedInterval.html?search= Calculates the product of all elements in the iterator. ```APIDOC ## fn product

(self) -> P ### Description Iterates over the entire iterator, multiplying all the elements. ### Constraints - `P` must implement `Product`. - `Self` must implement `Sized`. ### Returns The product of the elements. ``` -------------------------------- ### ExponentialBackoff::from_millis Source: https://docs.rs/tokio-retry/0.3.2/tokio_retry/strategy/struct.ExponentialBackoff.html?search=u32+-%3E+bool Constructs a new exponential back-off strategy with a base duration in milliseconds. The delay is calculated as base^n, where n is the number of past attempts. ```APIDOC ## ExponentialBackoff::from_millis ### Description Constructs a new exponential back-off strategy, given a base duration in milliseconds. The resulting duration is calculated by taking the base to the `n`-th power, where `n` denotes the number of past attempts. ### Signature ```rust pub const fn from_millis(base: u64) -> Self ``` ```