Skip to content

Commit 86a6256

Browse files
committed
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).
1 parent 57ef015 commit 86a6256

File tree

1 file changed

+35
-35
lines changed

1 file changed

+35
-35
lines changed

src/libstd/panic.rs

+35-35
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,14 @@ pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> {
3939
take_hook()
4040
}
4141

42-
/// A marker trait which represents "panic safe" types in Rust.
42+
/// A marker trait which represents "unwind safe" types in Rust.
4343
///
4444
/// This trait is implemented by default for many types and behaves similarly in
4545
/// terms of inference of implementation to the `Send` and `Sync` traits. The
46-
/// purpose of this trait is to encode what types are safe to cross a `recover`
47-
/// boundary with no fear of panic safety.
46+
/// purpose of this trait is to encode what types are safe to cross a `catch_unwind`
47+
/// boundary with no fear of unwind safety.
4848
///
49-
/// ## What is panic safety?
49+
/// ## What is unwind safety?
5050
///
5151
/// In Rust a function can "return" early if it either panics or calls a
5252
/// function which transitively panics. This sort of control flow is not always
@@ -59,62 +59,62 @@ pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> {
5959
///
6060
/// Typically in Rust, it is difficult to perform step (2) because catching a
6161
/// panic involves either spawning a thread (which in turns makes it difficult
62-
/// to later witness broken invariants) or using the `recover` function in this
62+
/// to later witness broken invariants) or using the `catch_unwind` function in this
6363
/// module. Additionally, even if an invariant is witnessed, it typically isn't a
64-
/// problem in Rust because there's no uninitialized values (like in C or C++).
64+
/// problem in Rust because there are no uninitialized values (like in C or C++).
6565
///
6666
/// It is possible, however, for **logical** invariants to be broken in Rust,
67-
/// which can end up causing behavioral bugs. Another key aspect of panic safety
67+
/// which can end up causing behavioral bugs. Another key aspect of unwind safety
6868
/// in Rust is that, in the absence of `unsafe` code, a panic cannot lead to
6969
/// memory unsafety.
7070
///
71-
/// That was a bit of a whirlwind tour of panic safety, but for more information
72-
/// about panic safety and how it applies to Rust, see an [associated RFC][rfc].
71+
/// That was a bit of a whirlwind tour of unwind safety, but for more information
72+
/// about unwind safety and how it applies to Rust, see an [associated RFC][rfc].
7373
///
7474
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
7575
///
7676
/// ## What is `UnwindSafe`?
7777
///
78-
/// Now that we've got an idea of what panic safety is in Rust, it's also
78+
/// Now that we've got an idea of what unwind safety is in Rust, it's also
7979
/// important to understand what this trait represents. As mentioned above, one
80-
/// way to witness broken invariants is through the `recover` function in this
80+
/// way to witness broken invariants is through the `catch_unwind` function in this
8181
/// module as it allows catching a panic and then re-using the environment of
8282
/// the closure.
8383
///
8484
/// Simply put, a type `T` implements `UnwindSafe` if it cannot easily allow
85-
/// witnessing a broken invariant through the use of `recover` (catching a
85+
/// witnessing a broken invariant through the use of `catch_unwind` (catching a
8686
/// panic). This trait is a marker trait, so it is automatically implemented for
87-
/// many types, and it is also structurally composed (e.g. a struct is recover
88-
/// safe if all of its components are recover safe).
87+
/// many types, and it is also structurally composed (e.g. a struct is unwind
88+
/// safe if all of its components are unwind safe).
8989
///
9090
/// Note, however, that this is not an unsafe trait, so there is not a succinct
9191
/// contract that this trait is providing. Instead it is intended as more of a
92-
/// "speed bump" to alert users of `recover` that broken invariants may be
92+
/// "speed bump" to alert users of `catch_unwind` that broken invariants may be
9393
/// witnessed and may need to be accounted for.
9494
///
9595
/// ## Who implements `UnwindSafe`?
9696
///
9797
/// Types such as `&mut T` and `&RefCell<T>` are examples which are **not**
98-
/// recover safe. The general idea is that any mutable state which can be shared
99-
/// across `recover` is not recover safe by default. This is because it is very
100-
/// easy to witness a broken invariant outside of `recover` as the data is
98+
/// unwind safe. The general idea is that any mutable state which can be shared
99+
/// across `catch_unwind` is not unwind safe by default. This is because it is very
100+
/// easy to witness a broken invariant outside of `catch_unwind` as the data is
101101
/// simply accessed as usual.
102102
///
103-
/// Types like `&Mutex<T>`, however, are recover safe because they implement
103+
/// Types like `&Mutex<T>`, however, are unwind safe because they implement
104104
/// poisoning by default. They still allow witnessing a broken invariant, but
105105
/// they already provide their own "speed bumps" to do so.
106106
///
107107
/// ## When should `UnwindSafe` be used?
108108
///
109109
/// Is not intended that most types or functions need to worry about this trait.
110-
/// It is only used as a bound on the `recover` function and as mentioned above,
110+
/// It is only used as a bound on the `catch_unwind` function and as mentioned above,
111111
/// the lack of `unsafe` means it is mostly an advisory. The `AssertUnwindSafe`
112112
/// wrapper struct in this module can be used to force this trait to be
113-
/// implemented for any closed over variables passed to the `recover` function
113+
/// implemented for any closed over variables passed to the `catch_unwind` function
114114
/// (more on this below).
115115
#[stable(feature = "catch_unwind", since = "1.9.0")]
116116
#[rustc_on_unimplemented = "the type {Self} may not be safely transferred \
117-
across a recover boundary"]
117+
across an unwind boundary"]
118118
pub trait UnwindSafe {}
119119

120120
/// Deprecated, renamed to UnwindSafe
@@ -126,7 +126,7 @@ pub trait RecoverSafe {}
126126
impl<T: UnwindSafe> RecoverSafe for T {}
127127

128128
/// A marker trait representing types where a shared reference is considered
129-
/// recover safe.
129+
/// unwind safe.
130130
///
131131
/// This trait is namely not implemented by `UnsafeCell`, the root of all
132132
/// interior mutability.
@@ -136,31 +136,31 @@ impl<T: UnwindSafe> RecoverSafe for T {}
136136
#[stable(feature = "catch_unwind", since = "1.9.0")]
137137
#[rustc_on_unimplemented = "the type {Self} contains interior mutability \
138138
and a reference may not be safely transferrable \
139-
across a recover boundary"]
139+
across a catch_unwind boundary"]
140140
pub trait RefUnwindSafe {}
141141

142-
/// A simple wrapper around a type to assert that it is panic safe.
142+
/// A simple wrapper around a type to assert that it is unwind safe.
143143
///
144-
/// When using `recover` it may be the case that some of the closed over
145-
/// variables are not panic safe. For example if `&mut T` is captured the
146-
/// compiler will generate a warning indicating that it is not panic safe. It
144+
/// When using `catch_unwind` it may be the case that some of the closed over
145+
/// variables are not unwind safe. For example if `&mut T` is captured the
146+
/// compiler will generate a warning indicating that it is not unwind safe. It
147147
/// may not be the case, however, that this is actually a problem due to the
148-
/// specific usage of `recover` if panic safety is specifically taken into
148+
/// specific usage of `catch_unwind` if unwind safety is specifically taken into
149149
/// account. This wrapper struct is useful for a quick and lightweight
150-
/// annotation that a variable is indeed panic safe.
150+
/// annotation that a variable is indeed unwind safe.
151151
///
152152
/// # Examples
153153
///
154154
/// One way to use `AssertUnwindSafe` is to assert that the entire closure
155-
/// itself is recover safe, bypassing all checks for all variables:
155+
/// itself is unwind safe, bypassing all checks for all variables:
156156
///
157157
/// ```
158158
/// use std::panic::{self, AssertUnwindSafe};
159159
///
160160
/// let mut variable = 4;
161161
///
162162
/// // This code will not compile because the closure captures `&mut variable`
163-
/// // which is not considered panic safe by default.
163+
/// // which is not considered unwind safe by default.
164164
///
165165
/// // panic::catch_unwind(|| {
166166
/// // variable += 3;
@@ -239,7 +239,7 @@ impl<T> UnwindSafe for AssertUnwindSafe<T> {}
239239
impl<T> UnwindSafe for AssertRecoverSafe<T> {}
240240

241241
// not covered via the Shared impl above b/c the inner contents use
242-
// Cell/AtomicUsize, but the usage here is recover safe so we can lift the
242+
// Cell/AtomicUsize, but the usage here is unwind safe so we can lift the
243243
// impl up one level to Arc/Rc itself
244244
#[stable(feature = "catch_unwind", since = "1.9.0")]
245245
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Rc<T> {}
@@ -352,9 +352,9 @@ impl<R, F: FnOnce() -> R> FnOnce<()> for AssertRecoverSafe<F> {
352352
/// that all captured variables are safe to cross this boundary. The purpose of
353353
/// this bound is to encode the concept of [exception safety][rfc] in the type
354354
/// system. Most usage of this function should not need to worry about this
355-
/// bound as programs are naturally panic safe without `unsafe` code. If it
355+
/// bound as programs are naturally unwind safe without `unsafe` code. If it
356356
/// becomes a problem the associated `AssertUnwindSafe` wrapper type in this
357-
/// module can be used to quickly assert that the usage here is indeed exception
357+
/// module can be used to quickly assert that the usage here is indeed unwind
358358
/// safe.
359359
///
360360
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md

0 commit comments

Comments
 (0)