Trait std::panic::UnwindSafe [−] [src]

pub trait UnwindSafe { }

A marker trait which represents "panic safe" types in Rust.

This trait is implemented by default for many types and behaves similarly in terms of inference of implementation to the Send and Sync traits. The purpose of this trait is to encode what types are safe to cross a recover boundary with no fear of panic safety.

What is panic safety?

In Rust a function can "return" early if it either panics or calls a function which transitively panics. This sort of control flow is not always anticipated, and has the possibility of causing subtle bugs through a combination of two cricial components:

  1. A data structure is in a temporarily invalid state when the thread panics.
  2. This broken invariant is then later observed.

Typically in Rust, it is difficult to perform step (2) because catching a panic involves either spawning a thread (which in turns makes it difficult to later witness broken invariants) or using the recover function in this module. Additionally, even if an invariant is witnessed, it typically isn't a problem in Rust because there's no uninitialized values (like in C or C++).

It is possible, however, for logical invariants to be broken in Rust, which can end up causing behavioral bugs. Another key aspect of panic safety in Rust is that, in the absence of unsafe code, a panic cannot lead to memory unsafety.

That was a bit of a whirlwind tour of panic safety, but for more information about panic safety and how it applies to Rust, see an associated RFC.

What is RecoverSafe?

Now that we've got an idea of what panic safety is in Rust, it's also important to understand what this trait represents. As mentioned above, one way to witness broken invariants is through the recover function in this module as it allows catching a panic and then re-using the environment of the closure.

Simply put, a type T implements RecoverSafe if it cannot easily allow witnessing a broken invariant through the use of recover (catching a panic). This trait is a marker trait, so it is automatically implemented for many types, and it is also structurally composed (e.g. a struct is recover safe if all of its components are recover safe).

Note, however, that this is not an unsafe trait, so there is not a succinct contract that this trait is providing. Instead it is intended as more of a "speed bump" to alert users of recover that broken invariants may be witnessed and may need to be accounted for.

Who implements UnwindSafe?

Types such as &mut T and &RefCell<T> are examples which are not recover safe. The general idea is that any mutable state which can be shared across recover is not recover safe by default. This is because it is very easy to witness a broken invariant outside of recover as the data is simply accessed as usual.

Types like &Mutex<T>, however, are recover safe because they implement poisoning by default. They still allow witnessing a broken invariant, but they already provide their own "speed bumps" to do so.

When should UnwindSafe be used?

Is not intended that most types or functions need to worry about this trait. It is only used as a bound on the recover function and as mentioned above, the lack of unsafe means it is mostly an advisory. The AssertRecoverSafe wrapper struct in this module can be used to force this trait to be implemented for any closed over variables passed to the recover function (more on this below).

Implementors