Struct RetryError 

pub(crate) struct RetryError<E> {
    pub(crate) doing: String,
    pub(crate) errors: Vec<(Attempt, E, Instant)>,
    pub(crate) n_errors: usize,
    pub(crate) first_error_at: Option<SystemTime>,
}

An error type for use when we’re going to do something a few times, and they might all fail.

To use this error type, initialize a new RetryError before you start trying to do whatever it is. Then, every time the operation fails, use RetryError::push() to add a new error to the list of errors. If the operation fails too many times, you can use RetryError as an Error itself.

This type now tracks timestamps for each error occurrence, allowing users to see when errors occurred and how long the retry process took.

Fields

doing: String

errors: Vec<(Attempt, E, Instant)>

n_errors: usize

first_error_at: Option<SystemTime>

Implementations

impl<E> RetryError<E>

pub fn in_attempt_to<T>(doing: T) -> RetryError<E>

where T: Into<String>,

Create a new RetryError, with no failed attempts.

The provided doing argument is a short string that describes what we were trying to do when we failed too many times. It will be used to format the final error message; it should be a phrase that can go after “while trying to”.

This RetryError should not be used as-is, since when no Errors have been pushed into it, it doesn’t represent an actual failure.

pub fn push_timed<T>( &mut self, err: T, instant: Instant, wall_clock: Option<SystemTime>, )

where T: Into<E>,

Add an error to this RetryError with explicit timestamps.

You should call this method when an attempt at the underlying operation has failed.

The instant parameter should be the monotonic time when the error occurred, typically obtained from a runtime’s now() method.

The wall_clock parameter is the wall-clock time when the error occurred, used for human-readable display. Pass None to skip wall-clock tracking, or Some(SystemTime::now()) for the current time.

Example

let mut retry_err: RetryError<&str> = RetryError::in_attempt_to("connect");
let now = Instant::now();
retry_err.push_timed("connection failed", now, Some(SystemTime::now()));

pub fn push<T>(&mut self, err: T)

where T: Into<E>,

Add an error to this RetryError using the current time.

You should call this method when an attempt at the underlying operation has failed.

This is a convenience wrapper around push_timed() that uses Instant::now() and SystemTime::now() for the timestamps. For code that needs mockable time (such as in tests), prefer push_timed().

pub fn sources(&self) -> impl Iterator<Item = &E>

Return an iterator over all of the reasons that the attempt behind this RetryError has failed.

pub fn len(&self) -> usize

Return the number of underlying errors.

pub fn is_empty(&self) -> bool

Return true if no underlying errors have been added.

pub fn extend<T>(&mut self, iter: impl IntoIterator<Item = T>)

where T: Into<E>,

Add multiple errors to this RetryError using the current time.

This method uses push() internally, which captures SystemTime::now(). For code that needs mockable time (such as in tests), iterate manually and call push_timed() instead.

Example

let mut err: RetryError<anyhow::Error> = RetryError::in_attempt_to("parse");
let errors = vec!["error1", "error2"].into_iter().map(anyhow::Error::msg);
err.extend(errors);

pub fn dedup_by<F>(&mut self, same_err: F)

where F: Fn(&E, &E) -> bool,

Group up consecutive errors of the same kind, for easier display.

Two errors have “the same kind” if they return true when passed to the provided same_err function.

pub fn extend_from_retry_error(&mut self, other: RetryError<E>)

Add multiple errors to this RetryError, preserving their original timestamps.

The errors from other will be added to this RetryError, with their original timestamps retained. The Attempt counters will be updated to continue from the current state of this RetryError. Attempt::Range entries are preserved as ranges

impl<E> RetryError<E>

where E: PartialEq,

pub fn dedup(&mut self)

Group up consecutive errors of the same kind, according to the PartialEq implementation.

Trait Implementations

impl<E> Clone for RetryError<E>

where E: Clone,

fn clone(&self) -> RetryError<E>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E> Debug for RetryError<E>

where E: Debug,

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

Formats the value using the given formatter.

impl<E> Display for RetryError<E>

where E: AsRef<dyn Error>,

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

Formats the value using the given formatter.

impl<E> Error for RetryError<E>

where E: Debug + AsRef<dyn Error>,

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<E> From<BackoffError<E>> for RetryError<E>

fn from(e: BackoffError<E>) -> Self

Converts to this type from the input type.

impl<E> IntoIterator for RetryError<E>

type Item = E

The type of the elements being iterated over.

type IntoIter = IntoIter<E>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <RetryError<E> as IntoIterator>::IntoIter

Creates an iterator from a value.