Trait StackError

Source

pub trait StackError: Error {
    // Required methods
    fn location(&self) -> Location;
    fn type_name(&self) -> &'static str;

    // Provided methods
    fn stack_source(&self) -> Option<&dyn StackError> { ... }
    fn depth(&self) -> usize { ... }
}

Expand description

Error trait extension that adds source code location tracking.

Types implementing this trait carry a Location at each level of the error chain, enabling StackReport to produce stack-trace-like output.

§Design note: no `Send + Sync` supertrait

This trait requires only Error, not Send + Sync + 'static (unlike anyhow/eyre). This aligns with snafu, which does not impose Send + Sync on error types. BoxedStackError adds Send + Sync bounds for the thread-safe trait object case.

§Design note: unsealed trait

This trait is intentionally unsealed — external crates may implement it for custom wrapper types (e.g., similar to BoxedStackError). Future method additions must provide default implementations to avoid breaking downstream impls.

§Deriving

Use #[suzunari_error] (recommended) or #[derive(StackError)] directly. Both resolve the location field via #[stack(location)] or by detecting a Location-typed field. Manual impl is only needed for wrapper types like BoxedStackError.

§Example

use suzunari_error::*;

#[suzunari_error]
#[suzu(display("fetch failed for {url}"))]
struct FetchError {
    url: String,
    source: std::io::Error,
}

fn fetch(url: &str) -> Result<(), FetchError> {
    std::fs::read(url).context(FetchSnafu { url })?;
    Ok(())
}

let err = fetch("/nonexistent").unwrap_err();

// StackError methods:
assert!(err.location().file().ends_with(".rs"));
assert_eq!(err.type_name(), "FetchError");
assert!(err.stack_source().is_none()); // io::Error is not StackError
assert_eq!(err.depth(), 1);            // 1 cause in the chain

Required Methods§

Source

fn location(&self) -> Location

Returns the location where this error was constructed.

Source

fn type_name(&self) -> &'static str

Returns a human-readable type name for display in stack traces.

The derive macro generates this as a &'static str literal:

Structs: "StructName"
Enum variants: "EnumName::VariantName"

Generic type parameters are not included. This is intended for display purposes only — do not parse or match against it programmatically.

Provided Methods§

Source

fn stack_source(&self) -> Option<&dyn StackError>

Returns the source error as a StackError, if available.

This enables StackReport to traverse the error chain with location info. The derive macro generates this automatically using autoref specialization (see the __private module).

§Contract

If stack_source() returns Some(s), then Error::source() must also return Some(e) where e and s refer to the same underlying error value (i.e., s is a &dyn StackError view of the &dyn Error returned by source()). The derive macro upholds this automatically; manual impls must ensure consistency.

Violating this contract causes StackReport to produce incomplete output in release builds (the debug_assert! that checks this is stripped). In debug builds, a panic will occur instead.

Source

fn depth(&self) -> usize

Returns the number of errors in the Error::source() chain (excluding self).

Traverses the full Error::source() chain (not stack_source()), counting both StackError and non-StackError causes.

Note: this count may differ from the number of lines in StackReport output, which also shows the top-level error on the first line.

Trait StackError Copy item path

§Design note: no Send + Sync supertrait

§Design note: unsealed trait

§Deriving

§Example

Required Methods§

fn location(&self) -> Location

fn type_name(&self) -> &'static str

Provided Methods§

fn stack_source(&self) -> Option<&dyn StackError>

§Contract

fn depth(&self) -> usize

Trait Implementations§

impl Error for Box<dyn StackError>

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

fn description(&self) -> &str

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

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

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

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

fn description(&self) -> &str

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

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

impl From<BoxedStackError> for Box<dyn StackError + Send + Sync>

fn from(inner: BoxedStackError) -> Self

impl StackError for Box<dyn StackError>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

fn depth(&self) -> usize

impl StackError for Box<dyn StackError + Send + Sync>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

fn depth(&self) -> usize

Implementations on Foreign Types§

impl StackError for Box<dyn StackError + Send + Sync>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

impl StackError for Box<dyn StackError>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

impl<T: StackError> StackError for Box<T>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

impl<T: ?Sized + StackError> StackError for Arc<T>

fn location(&self) -> Location

fn type_name(&self) -> &'static str

fn stack_source(&self) -> Option<&dyn StackError>

Implementors§

impl StackError for BoxedStackError

Trait StackError

§Design note: no `Send + Sync` supertrait