Struct Retry

pub struct Retry {
    initial_backoff: Duration,
    factor: f64,
    clamp_backoff: Duration,
    max_duration: Duration,
    max_tries: usize,
}

Available on crate feature async only.

Configures a retry operation.

See the module documentation for usage examples.

Fields

initial_backoff: Duration

factor: f64

clamp_backoff: Duration

max_duration: Duration

max_tries: usize

Implementations

impl Retry

pub(crate) fn project<'pin>( self: Pin<&'pin mut Self>, ) -> __RetryProjection<'pin>

pub(crate) fn project_ref<'pin>( self: Pin<&'pin Self>, ) -> __RetryProjectionRef<'pin>

impl Retry

pub fn initial_backoff(self, initial_backoff: Duration) -> Self

Sets the initial backoff for the retry operation.

The initial backoff is the amount of time to wait if the first try fails.

pub fn clamp_backoff(self, clamp_backoff: Duration) -> Self

Clamps the maximum backoff for the retry operation.

The maximum backoff is the maximum amount of time to wait between tries.

pub fn factor(self, factor: f64) -> Self

Sets the exponential backoff factor for the retry operation.

The time to wait is multiplied by this factor after each failed try. The default factor is two.

pub fn max_tries(self, max_tries: usize) -> Self

Sets the maximum number of tries.

If the operation is still failing after max_tries, then retry will return the last error.

Calls to max_tries will override any previous calls to max_tries.

Panics

Panics if max_tries is zero.

pub fn max_duration(self, duration: Duration) -> Self

Sets the maximum duration.

If the operation is still failing after the specified duration, then the operation will be retried once more and retry will return the last error.

Calls to max_duration will override any previous calls to max_duration.

pub fn retry<F, R, T, E>(self, f: F) -> Result<T, E>

where F: FnMut(RetryState) -> R, R: Into<RetryResult<T, E>>,

Retries the fallible operation f according to the configured policy.

The retry method invokes f repeatedly until it returns either RetryResult::Ok or RetryResult::FatalErr, or until the maximum duration or tries have been reached, as configured via max_duration or max_tries. If the last invocation of f returns RetryResult::Ok(t), then retry returns Ok(t). If the last invocation of f returns RetryResult::RetriableErr(e) or RetryResult::FatalErr(e), then retry returns Err(e).

As a convenience, f can return any type that is convertible to a RetryResult. The conversion from Result to RetryResult converts Err(e) to RetryResult::RetryableErr(e), that is, it considers all errors retryable.

After the first failure, retry sleeps for the initial backoff configured via initial_backoff. After each successive failure, retry sleeps for twice the last backoff. If the backoff would ever exceed the maximum backoff configured viq Retry::clamp_backoff, then the backoff is clamped to the specified maximum.

The operation does not attempt to forcibly time out f, even if there is a maximum duration. If there is the possibility of f blocking forever, consider adding a timeout internally.

pub async fn retry_async<F, U, R, T, E>(self, f: F) -> Result<T, E>

where F: FnMut(RetryState) -> U, U: Future<Output = R>, R: Into<RetryResult<T, E>>,

Like Retry::retry but for asynchronous operations.

pub async fn retry_async_canceling<F, U, T, E>(self, f: F) -> Result<T, E>

where F: FnMut(RetryState) -> U, U: Future<Output = Result<T, E>>, E: From<Elapsed> + Debug,

Like Retry::retry_async but the operation will be canceled if the maximum duration is reached.

Specifically, if the maximum duration is reached, the operation f will be forcibly canceled by dropping it. Canceling f can be surprising if the operation is not programmed to expect the possibility of not resuming from an await point; if you wish to always run f to completion, use Retry::retry_async instead.

If f is forcibly canceled, the error returned will be the error returned by the prior invocation of f. If there is no prior invocation of f, then an Elapsed error is returned. The idea is that if f fails three times in a row with a useful error message, and then the fourth attempt is canceled because the timeout is reached, the caller would rather see the useful error message from the third attempt, rather than the “deadline exceeded” message from the fourth attempt.

pub async fn retry_async_with_state<F, S, U, R, T, E>( self, user_state: S, f: F, ) -> (S, Result<T, E>)

where F: FnMut(RetryState, S) -> U, U: Future<Output = (S, R)>, R: Into<RetryResult<T, E>>,

Like Retry::retry_async but can pass around user specified state.

pub async fn retry_async_with_state_canceling<F, S, U, R, T, E>( self, user_state: S, f: F, ) -> Result<T, E>

where F: FnMut(RetryState, S) -> U, U: Future<Output = (S, R)>, R: Into<RetryResult<T, E>>, E: From<Elapsed> + Debug,

Combines Retry::retry_async_canceling and Retry::retry_async_with_state, so that both timeouts are respected and user state can be passed in (bot not be read out).

pub fn into_retry_stream(self) -> RetryStream

Convert into RetryStream

Trait Implementations

impl Debug for Retry

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

Formats the value using the given formatter.

impl Default for Retry

fn default() -> Self

Constructs a retry operation that will retry forever with backoff defaults that are reasonable for a fallible network operation.

impl<'pin> Unpin for Retry

where PinnedFieldsOf<__Retry<'pin>>: Unpin,