take_hook()
}
-/// A marker trait which represents "panic safe" types in Rust.
+/// A marker trait which represents "unwind 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.
+/// purpose of this trait is to encode what types are safe to cross a `catch_unwind`
+/// boundary with no fear of unwind safety.
///
-/// ## What is panic safety?
+/// ## What is unwind 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
///
/// 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
+/// to later witness broken invariants) or using the `catch_unwind` 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++).
+/// problem in Rust because there are 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
+/// which can end up causing behavioral bugs. Another key aspect of unwind 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][rfc].
+/// That was a bit of a whirlwind tour of unwind safety, but for more information
+/// about unwind safety and how it applies to Rust, see an [associated RFC][rfc].
///
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
///
/// ## What is `UnwindSafe`?
///
-/// Now that we've got an idea of what panic safety is in Rust, it's also
+/// Now that we've got an idea of what unwind 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
+/// way to witness broken invariants is through the `catch_unwind` 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 `UnwindSafe` if it cannot easily allow
-/// witnessing a broken invariant through the use of `recover` (catching a
+/// witnessing a broken invariant through the use of `catch_unwind` (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).
+/// many types, and it is also structurally composed (e.g. a struct is unwind
+/// safe if all of its components are unwind 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
+/// "speed bump" to alert users of `catch_unwind` 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
+/// unwind safe. The general idea is that any mutable state which can be shared
+/// across `catch_unwind` is not unwind safe by default. This is because it is very
+/// easy to witness a broken invariant outside of `catch_unwind` as the data is
/// simply accessed as usual.
///
-/// Types like `&Mutex<T>`, however, are recover safe because they implement
+/// Types like `&Mutex<T>`, however, are unwind 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,
+/// It is only used as a bound on the `catch_unwind` function and as mentioned above,
/// the lack of `unsafe` means it is mostly an advisory. The `AssertUnwindSafe`
/// 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
+/// implemented for any closed over variables passed to the `catch_unwind` function
/// (more on this below).
#[stable(feature = "catch_unwind", since = "1.9.0")]
#[rustc_on_unimplemented = "the type {Self} may not be safely transferred \
- across a recover boundary"]
+ across an unwind boundary"]
pub trait UnwindSafe {}
/// Deprecated, renamed to UnwindSafe
impl<T: UnwindSafe> RecoverSafe for T {}
/// A marker trait representing types where a shared reference is considered
-/// recover safe.
+/// unwind safe.
///
/// This trait is namely not implemented by `UnsafeCell`, the root of all
/// interior mutability.
#[stable(feature = "catch_unwind", since = "1.9.0")]
#[rustc_on_unimplemented = "the type {Self} contains interior mutability \
and a reference may not be safely transferrable \
- across a recover boundary"]
+ across a catch_unwind boundary"]
pub trait RefUnwindSafe {}
-/// A simple wrapper around a type to assert that it is panic safe.
+/// A simple wrapper around a type to assert that it is unwind safe.
///
-/// When using `recover` it may be the case that some of the closed over
-/// variables are not panic safe. For example if `&mut T` is captured the
-/// compiler will generate a warning indicating that it is not panic safe. It
+/// When using `catch_unwind` it may be the case that some of the closed over
+/// variables are not unwind safe. For example if `&mut T` is captured the
+/// compiler will generate a warning indicating that it is not unwind safe. It
/// may not be the case, however, that this is actually a problem due to the
-/// specific usage of `recover` if panic safety is specifically taken into
+/// specific usage of `catch_unwind` if unwind safety is specifically taken into
/// account. This wrapper struct is useful for a quick and lightweight
-/// annotation that a variable is indeed panic safe.
+/// annotation that a variable is indeed unwind safe.
///
/// # Examples
///
/// One way to use `AssertUnwindSafe` is to assert that the entire closure
-/// itself is recover safe, bypassing all checks for all variables:
+/// itself is unwind safe, bypassing all checks for all variables:
///
/// ```
/// use std::panic::{self, AssertUnwindSafe};
/// let mut variable = 4;
///
/// // This code will not compile because the closure captures `&mut variable`
-/// // which is not considered panic safe by default.
+/// // which is not considered unwind safe by default.
///
/// // panic::catch_unwind(|| {
/// // variable += 3;
impl<T> UnwindSafe for AssertRecoverSafe<T> {}
// not covered via the Shared impl above b/c the inner contents use
-// Cell/AtomicUsize, but the usage here is recover safe so we can lift the
+// Cell/AtomicUsize, but the usage here is unwind safe so we can lift the
// impl up one level to Arc/Rc itself
#[stable(feature = "catch_unwind", since = "1.9.0")]
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Rc<T> {}
/// that all captured variables are safe to cross this boundary. The purpose of
/// this bound is to encode the concept of [exception safety][rfc] in the type
/// system. Most usage of this function should not need to worry about this
-/// bound as programs are naturally panic safe without `unsafe` code. If it
+/// bound as programs are naturally unwind safe without `unsafe` code. If it
/// becomes a problem the associated `AssertUnwindSafe` wrapper type in this
-/// module can be used to quickly assert that the usage here is indeed exception
+/// module can be used to quickly assert that the usage here is indeed unwind
/// safe.
///
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
projects / rust.git / commitdiff