Struct Error

pub struct Error {
    pub stack: ThinVec<(ErrorKind, Option<&'static Location<'static>>)>,
}

An error struct intended for high level error propogation with programmable backtraces

For lower level error propogation, you should still use ordinary Option and Result with domain-specific enums, it is only when using OS-level functions or when multiple domains converge that this is intended to be used. This has an internal stack for different kinds of arbitrary lower level errors and Locations. When used with the StackableErr trait, this enables easy conversion and software defined backtraces for better async debugging. See the crate docs for more.

Note that due to trait conflicts and not wanting users to accidentally wastefully embed stacked_errors::Error in a BoxedErr of another stacked_errors::Error, stacked_errors::Error itself does not actually implement core::error::Error. This does not pose a problem in most cases since it is intended to be the highest level of error that is directly returned or panicked on. However, if a user needs the end result struct to implement core::error::Error, they can use the StackedError wrapper.

Fields

stack: ThinVec<(ErrorKind, Option<&'static Location<'static>>)>

Using a ThinVec has advantages such as taking as little space as possible on the stack (since we are commiting to some indirection at this point), and having the niche optimizations applied to things like Result<(), Error>.

Implementations

impl Error

Note: in most cases you can use Error::from or a call from StackableErr instead of these functions.

pub fn empty() -> Self

Returns an empty error stack

pub fn new() -> Self

Returns an error stack with just a UnitError and location information

pub fn from_kind<K: Into<ErrorKind>>(kind: K) -> Self

Returns an error stack with just kind. The impl From<_> for Error implementations can usually be used in place of this.

pub fn from_kind_locationless<K: Into<ErrorKind>>(kind: K) -> Self

Same as Error::from_kind but without location.

pub fn from_box(e: Box<dyn Error + Send + Sync>) -> Self

Returns an error stack with just a BoxedErr.

pub fn from_box_locationless(e: Box<dyn Error + Send + Sync>) -> Self

Same as Error::from_box but without location.

pub fn box_from<E: Error + Send + Sync + 'static>(e: E) -> Self

Returns an error stack with a BoxedError around e, and location info. Error::from_kind or Error::from is more efficient and should be used instead if the type implements Into<ErrorKind>.

pub fn box_from_locationless<E: Error + Send + Sync + 'static>(e: E) -> Self

Same as Error::box_from but without location.

pub fn add_kind<K: Into<ErrorKind>>(self, kind: K) -> Self

Adds kind to the error stack alongside location information. Use StackableErr instead of this if anything expensive in creating the error is involved, because stack_err uses a closure analogous to ok_or_else.

pub fn add_kind_locationless<K: Into<ErrorKind>>(self, kind: K) -> Self

Same as Error::add_kind but without location.

pub fn add_box(self, e: Box<dyn Error + Send + Sync>) -> Self

Adds e to the error stack alongside location information. Use StackableErr instead of this if anything expensive in creating the error is involved, because stack_err uses a closure analogous to ok_or_else.

pub fn add_box_locationless(self, e: Box<dyn Error + Send + Sync>) -> Self

Same as Error::add_box but without location.

pub fn box_and_add<E: Error + Send + Sync + 'static>(self, e: E) -> Self

Boxes a type implementing core::error::Error + Send + Sync + 'static and adds it with location data to the stack. Error::add_kind is preferred if possible, this is a shorthand for stack.add_kind(ErrorKind::from_box(Box::new(e))) where the error does not implement Into<ErrorKind> and needs to be boxed.

pub fn box_and_add_locationless<E: Error + Send + Sync + 'static>( self, e: E, ) -> Self

Same as Error::box_and_add but without location.

pub fn add_location(self) -> Self

Only adds track_caller location to the stack

pub fn chain_errors(self, other: Self) -> Self

Moves the stack of other onto self

pub fn timeout() -> Self

Returns a base TimeoutError error

pub fn probably_not_root_cause() -> Self

Returns a base ProbablyNotRootCauseError error

pub fn is_timeout(&self) -> bool

Returns if a TimeoutError is in the error stack

pub fn is_probably_not_root_cause(&self) -> bool

Returns if a ProbablyNotRootCauseError is in the error stack

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Default for Error

fn default() -> Self

Returns the “default value” for a type.

impl Display for Error

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

Formats the value using the given formatter.

impl From<&'static str> for Error

fn from(e: &'static str) -> Self

Converts to this type from the input type.

impl From<()> for Error

fn from(e: ()) -> Self

Converts to this type from the input type.

impl From<Box<dyn Error + Sync + Send>> for Error

fn from(e: Box<dyn Error + Send + Sync>) -> Self

Converts to this type from the input type.

impl From<Cow<'static, str>> for Error

fn from(e: Cow<'static, str>) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<FromUtf16Error> for Error

fn from(e: FromUtf16Error) -> Self

Converts to this type from the input type.

impl From<FromUtf8Error> for Error

fn from(e: FromUtf8Error) -> Self

Converts to this type from the input type.

impl From<ParseFloatError> for Error

fn from(e: ParseFloatError) -> Self

Converts to this type from the input type.

impl From<ParseIntError> for Error

fn from(e: ParseIntError) -> Self

Converts to this type from the input type.

impl From<String> for Error

fn from(e: String) -> Self

Converts to this type from the input type.

impl From<TryFromIntError> for Error

fn from(e: TryFromIntError) -> Self

Converts to this type from the input type.

impl StackableErr for Error

type Output = Result<(), Error>

fn stack_err<K: Into<ErrorKind>, F: FnOnce() -> K>(self, f: F) -> Self::Output

Pushes the result of f and location information to the error stack

fn stack_err_locationless<K: Into<ErrorKind>, F: FnOnce() -> K>( self, f: F, ) -> Self::Output

Pushes the result of f without location information to the error stack

fn stack(self) -> Self::Output

Pushes just location information to the error stack

fn stack_locationless(self) -> Self::Output

Only converts to Self::Output and pushes it on the error stack