# Trait failure::Fail [−] [src]

    pub trait Fail: Display + Debug + Send + Sync + 'static {
        fn cause(&self) -> Option<&Fail> { ... }
        fn backtrace(&self) -> Option<&Backtrace> { ... }
        fn context<D>(self, context: D) -> Context<D>
        where
            D: Display + Send + Sync + 'static,
            Self: Sized,
        { ... }
        fn compat(self) -> Compat<Self>
        where
            Self: Sized,
        { ... }
        fn causes(&self) -> Causes
        where
            Self: Sized,
        { ... }
        fn root_cause(&self) -> &Fail
        where
            Self: Sized,
        { ... }
    }

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 cause(&self) -> Option<&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,`

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,`

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`.

ⓘImportant traits for Causes<'f>

### Important traits for Causes<'f>

`impl<'f> Iterator for Causes<'f> type Item = &'f Fail;`

### `fn causes(&self) -> Causes where
Self: Sized,`

Returns a iterator over the causes of this `Fail` with itself as the first item and the `root_cause` as the final item.

### `fn root_cause(&self) -> &Fail where
Self: Sized,`

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.

## Methods

### `impl 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 root_cause(&self) -> &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.

####
ⓘImportant traits for Causes<'f>

### Important traits for Causes<'f>

`impl<'f> Iterator for Causes<'f> type Item = &'f Fail;`
`pub fn causes(&self) -> Causes`
[src]

Returns a iterator over the causes of this `Fail` with itself as the first item and the `root_cause` as the final item.

## Implementors

- [src]
  `impl<D: Display + Send + Sync + 'static> Fail for Context<D>`
- [src]
  `impl<E: Error + Send + 'static> Fail for SyncFailure<E>`
- [src]
  `impl<E: StdError + Send + Sync + 'static> Fail for E`

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)