Struct Exn 

pub struct Exn<E: Error + Send + Sync + 'static = Untyped> { /* private fields */ }

An exception type that can hold an error tree and the call site.

While an error chain, a list, is automatically created when raise and friends are invoked, one can also use Exn::raise_all to create an error that has multiple causes.

Native error sources

Values reached through std::error::Error::source() remain owned by their original errors and are traversed by reference, preserving their concrete types. They aren’t exception frames and therefore have no captured call site of their own.

In diagnostic reports, custom std::io::Error wrappers show their kind instead of repeating the payload’s diagnostic. The payload is reported separately as a cause; both remain available for inspection and classification.

Exn == Exn<Untyped>

Exn act’s like Box<dyn std::error::Error + Send + Sync + 'static>, but with the capability to store a tree of errors along with their call sites.

Visualisation

Linearized trees during display make a list of 3 children indistinguishable from 3 errors where each is the child of the other.

Debug

• locations: ✔️
• error display: Display
• tree mode: linearized

Debug + Alternate

• locations: ❌
• error display: Display
• tree mode: linearized

Display

• locations: ❌
• error display: Debug
• tree mode: None

Display + Alternate

• locations: ❌
• error display: Debug
• tree mode: verbatim

Implementations

impl<E: Error + Send + Sync + 'static> Exn<E>

pub fn new(error: E) -> Self

Create a new exception with the given error.

Its source chain is retained by error and traversed lazily for formatting, downcasting, and conversion. Native sources are not copied into owned Frame values and keep their concrete types.

See also ErrorExt::raise for a fluent way to convert an error into an Exn instance.

pub fn raise_all<T, I>(children: I, err: E) -> Self

where T: Error + Send + Sync + 'static, I: IntoIterator, I::Item: Into<Exn<T>>,

Create a new exception with the given error and children.

pub fn raise<T: Error + Send + Sync + 'static>(self, err: T) -> Exn<T>

Raise a new exception; this will make the current exception a child of the new one.

pub fn chain<T: Error + Send + Sync + 'static>( self, err: impl Into<Exn<T>>, ) -> Exn<E>

Use the current exception as the head of a chain, adding err to its children.

pub fn chain_all<T, I>(self, errors: I) -> Exn<E>

where T: Error + Send + Sync + 'static, I: IntoIterator, I::Item: Into<Exn<T>>,

Use the current exception the head of a chain, adding errors to its children.

pub fn drain_children(&mut self) -> impl Iterator<Item = Exn> + '_

Drain all explicitly added child frames of this error as untyped Exn.

Native Error::source() values remain owned by their error and aren’t drainable frames. This is useful if one wants to re-organise explicitly raised errors and the error layout is well known.

pub fn erased(self) -> Exn

Erase the type of this instance and turn it into a bare Exn.

pub fn error(&self) -> &E

Return the current exception.

pub fn into_box(self) -> Box<E>

Discard all error context and return the underlying error in a Box.

This is useful to retain the allocation, as internally it’s also stored in a box, when comparing it to Self::into_inner().

pub fn into_inner(self) -> E

Discard all error context and return the underlying error.

This may be needed to obtain something that once again implements Error. Note that this destroys the internal Box and moves the value back onto the stack.

pub fn into_error(self) -> Error

Turn ourselves into a top-level Error that implements std::error::Error.

pub fn into_chain(self) -> ChainedError

Convert this error tree into a chain of errors, breadth first, which flattens the tree but retains all type dynamic type information.

This is useful for inter-op with anyhow.

pub fn frame(&self) -> &Frame

Return the underlying exception frame.

pub fn iter(&self) -> impl Iterator<Item = &Frame>

Iterate over all explicitly created frames in breadth-first order. The first frame is this instance, followed by all explicitly raised children. Native Error::source() values are not frames.

pub fn iter_errors(&self) -> impl Iterator<Item = &(dyn Error + 'static)> + '_

Lazily visit stored errors and native sources in logical breadth-first order, expanding nested crate::Error values. Classification-only markers are skipped; other concrete types remain available for downcasting, as with crate::Error::iter_errors().

pub fn metadata(&self) -> impl Iterator<Item = &Metadata> + '_

Visit the non-empty Metadata dictionaries of crate::Message contexts in error traversal order. Dictionaries remain separate. Functions returning metadata document the keys in each context.

To match a class and values on the same message, use Self::classify() and Classification::error() instead of combining independent classification and metadata searches.

pub fn probable_cause(&self) -> &(dyn Error + 'static)

Return the error that is most likely the root cause, based on Frame::probable_cause().

Return the stored error if there is no unique causal child. Nested crate::Error graphs participate alongside native sources and explicit children, matching crate::Error::probable_cause() without consuming this exception.

pub fn downcast_any_ref<T: Error + 'static>(&self) -> Option<&T>

Find the first diagnostic error that downcasts to T in logical breadth-first order. Classification-only markers are omitted, as in Self::iter_errors().

Nested crate::Error values are inspected recursively, matching crate::Error::downcast_any_ref().

impl<E: Error + Send + Sync + 'static> Exn<E>

Classification helpers for inspecting an exception without consuming it or losing its typed outer error.

The corresponding helpers on crate::Error would require consuming the exception with into_error(), while dereferencing an exception only exposes its outer error E, not the full error tree. These helpers inspect that tree directly, so callers can recognize a failure’s meaning even when it is wrapped in context, and still propagate the original exception afterward.

pub fn classify(&self) -> Classifications<'_>

Return all known classifications in logical breadth-first order, including native sources and nested crate::Error values.

As with crate::Error::classify(), unknown errors are omitted, classifications aren’t deduplicated, and each item retains the classified error for downcasting and origin inspection.

pub fn is_retryable(&self) -> bool

Return true if any stored error or native source has an explicit crate::Class::Retryable classification.

crate::Message and crate::ClassificationMarker can supply this classification. Nested crate::Error values are inspected recursively. Unlike Self::can_retry(), this does not infer retryability from I/O error kinds.

pub fn is_resource_exhausted(&self) -> bool

Return true if any stored error or native source reports resource exhaustion.

This recognizes messages or markers with crate::Class::ResourceExhaustion, std::collections::TryReserveError, and std::io::ErrorKind::OutOfMemory, including within nested crate::Error values.

pub fn can_retry(&self) -> bool

Return true if any stored error, or an error in its source() chain, is:

• classified as crate::Class::Retryable, or
• classified as crate::Class::Io with kind Interrupted or TimedOut.

Nested crate::Error values are inspected recursively. false only means that no known retryable error was found; it does not guarantee that retrying cannot succeed.

pub fn can_retry_lenient(&self) -> bool

Apply Self::can_retry(), also accepting std::io::Error with kind UnexpectedEof, OutOfMemory, BrokenPipe, AddrInUse, ConnectionAborted, ConnectionReset, or ConnectionRefused.

This applies a more lenient policy than Self::can_retry. Nested crate::Error values are inspected recursively. false only means that no known retryable error was found; it does not guarantee that retrying cannot succeed.

pub fn is_corrupted(&self) -> bool

Return true if malformed or internally inconsistent data caused the failure.

pub fn is_not_found(&self) -> bool

Return true if a requested resource was not found.

pub fn is_validation(&self) -> bool

Return true if invalid input caused the failure.

Trait Implementations

impl<E: Error + Send + Sync + 'static> Debug for Exn<E>

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

Formats the value using the given formatter.

impl<E> Deref for Exn<E>

where E: Error + Send + Sync + 'static,

type Target = E

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<E: Error + Send + Sync + 'static> Display for Exn<E>

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

Formats the value using the given formatter.

impl<E: Error + Send + Sync + 'static> From<E> for Exn<E>

fn from(error: E) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Box<Frame>

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Box<dyn Error + Send + Sync + 'static>

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Error

where E: Error + Send + Sync + 'static,

Available on crate feature anyhow only.

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Frame

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for ChainedError

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Error

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl From<Frame> for Exn

fn from(frame: Frame) -> Self

Converts to this type from the input type.

impl<E: Error + Send + Sync + 'static> PartialEq<&str> for Exn<E>

fn eq(&self, other: &&str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: Error + Send + Sync + 'static> PartialEq<String> for Exn<E>

fn eq(&self, other: &String) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: Error + Send + Sync + 'static> PartialEq<str> for Exn<E>

fn eq(&self, other: &str) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.