[−][src]Trait failure::Fail
The Fail
trait.
Implementors of this trait are called 'failures'.
All error types should implement Fail
, which provides a baseline of
functionality that they all share.
Fail
has no required methods, but it does require that your type
implement several other traits:
Display
: to print a user-friendly representation of the error.Debug
: to print a verbose, developer-focused representation of the error.Send + Sync
: Your error type is required to be safe to transfer to and reference from another thread
Additionally, all failures must be 'static
. This enables downcasting.
Fail
provides several methods with default implementations. Two of these
may be appropriate to override depending on the definition of your
particular failure: the cause
and backtrace
methods.
The failure_derive
crate provides a way to derive the Fail
trait for
your type. Additionally, all types that already implement
std::error::Error
, and are also Send
, Sync
, and 'static
, implement
Fail
by a blanket impl.
Provided methods
fn name(&self) -> Option<&str>
Returns the "name" of the error.
This is typically the type name. Not all errors will implement this. This method is expected to be most useful in situations where errors need to be reported to external instrumentation systems such as crash reporters.
fn cause(&self) -> Option<&dyn Fail>
Returns a reference to the underlying cause of this failure, if it is an error that wraps other errors.
Returns None
if this failure does not have another error as its
underlying cause. By default, this returns None
.
This should never return a reference to self
, but only return
Some
when it can return a different failure. Users may loop
over the cause chain, and returning self
would result in an infinite
loop.
fn backtrace(&self) -> Option<&Backtrace>
Returns a reference to the Backtrace
carried by this failure, if it
carries one.
Returns None
if this failure does not carry a backtrace. By
default, this returns None
.
fn context<D>(self, context: D) -> Context<D> where
D: Display + Send + Sync + 'static,
Self: Sized,
D: Display + Send + Sync + 'static,
Self: Sized,
Provides context for this failure.
This can provide additional information about this error, appropriate to the semantics of the current layer. That is, if you have a lower-level error, such as an IO error, you can provide additional context about what that error means in the context of your function. This gives users of this function more information about what has gone wrong.
This takes any type that implements Display
, as well as
Send
/Sync
/'static
. In practice, this means it can take a String
or a string literal, or another failure, or some other custom context-carrying
type.
fn compat(self) -> Compat<Self> where
Self: Sized,
Self: Sized,
Wraps this failure in a compatibility wrapper that implements
std::error::Error
.
This allows failures to be compatible with older crates that
expect types that implement the Error
trait from std::error
.
Methods
impl dyn Fail
[src]
pub fn downcast_ref<T: Fail>(&self) -> Option<&T>
[src]
Attempts to downcast this failure to a concrete type by reference.
If the underlying error is not of type T
, this will return None
.
pub fn downcast_mut<T: Fail>(&mut self) -> Option<&mut T>
[src]
Attempts to downcast this failure to a concrete type by mutable reference.
If the underlying error is not of type T
, this will return None
.
pub fn find_root_cause(&self) -> &dyn Fail
[src]
Returns the "root cause" of this Fail
- the last value in the
cause chain which does not return an underlying cause
.
If this type does not have a cause, self
is returned, because
it is its own root cause.
This is equivalent to iterating over iter_causes()
and taking
the last item.
ⓘImportant traits for Causes<'f>pub fn iter_causes(&self) -> Causes
[src]
Returns a iterator over the causes of this Fail
with the cause
of this fail as the first item and the root_cause
as the final item.
Use iter_chain
to also include the fail itself.
ⓘImportant traits for Causes<'f>pub fn iter_chain(&self) -> Causes
[src]
Returns a iterator over all fails up the chain from the current
as the first item up to the root_cause
as the final item.
This means that the chain also includes the fail itself which
means that it does not start with cause
. To skip the outermost
fail use iter_causes
instead.
pub fn root_cause(&self) -> &dyn Fail
[src]
please use the 'find_root_cause()' method instead
Deprecated alias to find_root_cause
.
ⓘImportant traits for Causes<'f>pub fn causes(&self) -> Causes
[src]
please use the 'iter_chain()' method instead
Deprecated alias to iter_chain
.
Trait Implementations
Implementations on Foreign Types
impl Fail for Box<dyn Fail>
[src]
fn cause(&self) -> Option<&dyn Fail>
[src]
fn backtrace(&self) -> Option<&Backtrace>
[src]
fn name(&self) -> Option<&str>
[src]
fn context<D>(self, context: D) -> Context<D> where
D: Display + Send + Sync + 'static,
Self: Sized,
[src]
D: Display + Send + Sync + 'static,
Self: Sized,
fn compat(self) -> Compat<Self> where
Self: Sized,
[src]
Self: Sized,
Implementors
impl<D: Display + Send + Sync + 'static> Fail for Context<D>
[src]
fn name(&self) -> Option<&str>
[src]
fn cause(&self) -> Option<&dyn Fail>
[src]
fn backtrace(&self) -> Option<&Backtrace>
[src]
fn context<D>(self, context: D) -> Context<D> where
D: Display + Send + Sync + 'static,
Self: Sized,
[src]
D: Display + Send + Sync + 'static,
Self: Sized,
fn compat(self) -> Compat<Self> where
Self: Sized,
[src]
Self: Sized,
impl<E: Error + Send + 'static> Fail for SyncFailure<E>
[src]
fn name(&self) -> Option<&str>
[src]
fn cause(&self) -> Option<&dyn Fail>
[src]
fn backtrace(&self) -> Option<&Backtrace>
[src]
fn context<D>(self, context: D) -> Context<D> where
D: Display + Send + Sync + 'static,
Self: Sized,
[src]
D: Display + Send + Sync + 'static,
Self: Sized,
fn compat(self) -> Compat<Self> where
Self: Sized,
[src]
Self: Sized,