Struct mz_ore::retry::Retry

source ·

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

Available on crate feature async only.

Expand description

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§

source §

impl Retry

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source