From 86a62562700a1814b365478f36cf5e577c9a75e4 Mon Sep 17 00:00:00 2001 From: diwic Date: Tue, 24 May 2016 07:28:32 +0200 Subject: [PATCH] panic.rs: fix docs (recover -> catch_unwind) The current docs are a bit inconsistent. First, change all references of "recover" to "catch_unwind" because the function was renamed. Second, consistently use the term "unwind safe" instead of "panic safe", "exception safe" and "recover safe" (all these terms were used previously). --- src/libstd/panic.rs | 70 ++++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/src/libstd/panic.rs b/src/libstd/panic.rs index 3b170dc9c6d..6770eafeac9 100644 --- a/src/libstd/panic.rs +++ b/src/libstd/panic.rs @@ -39,14 +39,14 @@ pub fn take_handler() -> Box { 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 @@ -59,62 +59,62 @@ pub fn take_handler() -> Box { /// /// 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` 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`, however, are recover safe because they implement +/// Types like `&Mutex`, 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 @@ -126,7 +126,7 @@ pub trait RecoverSafe {} impl 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. @@ -136,23 +136,23 @@ impl RecoverSafe for T {} #[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}; @@ -160,7 +160,7 @@ pub trait RefUnwindSafe {} /// 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; @@ -239,7 +239,7 @@ impl UnwindSafe for AssertUnwindSafe {} impl UnwindSafe for AssertRecoverSafe {} // 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 UnwindSafe for Rc {} @@ -352,9 +352,9 @@ extern "rust-call" fn call_once(self, _args: ()) -> R { /// 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 -- 2.44.0