@@ -39,14 +39,14 @@ pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> {
39
39
take_hook ( )
40
40
}
41
41
42
- /// A marker trait which represents "panic safe" types in Rust.
42
+ /// A marker trait which represents "unwind safe" types in Rust.
43
43
///
44
44
/// This trait is implemented by default for many types and behaves similarly in
45
45
/// 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.
48
48
///
49
- /// ## What is panic safety?
49
+ /// ## What is unwind safety?
50
50
///
51
51
/// In Rust a function can "return" early if it either panics or calls a
52
52
/// 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> {
59
59
///
60
60
/// Typically in Rust, it is difficult to perform step (2) because catching a
61
61
/// 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
63
63
/// 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++).
65
65
///
66
66
/// 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
68
68
/// in Rust is that, in the absence of `unsafe` code, a panic cannot lead to
69
69
/// memory unsafety.
70
70
///
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].
73
73
///
74
74
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
75
75
///
76
76
/// ## What is `UnwindSafe`?
77
77
///
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
79
79
/// 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
81
81
/// module as it allows catching a panic and then re-using the environment of
82
82
/// the closure.
83
83
///
84
84
/// 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
86
86
/// 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).
89
89
///
90
90
/// Note, however, that this is not an unsafe trait, so there is not a succinct
91
91
/// 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
93
93
/// witnessed and may need to be accounted for.
94
94
///
95
95
/// ## Who implements `UnwindSafe`?
96
96
///
97
97
/// 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
101
101
/// simply accessed as usual.
102
102
///
103
- /// Types like `&Mutex<T>`, however, are recover safe because they implement
103
+ /// Types like `&Mutex<T>`, however, are unwind safe because they implement
104
104
/// poisoning by default. They still allow witnessing a broken invariant, but
105
105
/// they already provide their own "speed bumps" to do so.
106
106
///
107
107
/// ## When should `UnwindSafe` be used?
108
108
///
109
109
/// 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,
111
111
/// the lack of `unsafe` means it is mostly an advisory. The `AssertUnwindSafe`
112
112
/// 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
114
114
/// (more on this below).
115
115
#[ stable( feature = "catch_unwind" , since = "1.9.0" ) ]
116
116
#[ rustc_on_unimplemented = "the type {Self} may not be safely transferred \
117
- across a recover boundary"]
117
+ across an unwind boundary"]
118
118
pub trait UnwindSafe { }
119
119
120
120
/// Deprecated, renamed to UnwindSafe
@@ -126,7 +126,7 @@ pub trait RecoverSafe {}
126
126
impl < T : UnwindSafe > RecoverSafe for T { }
127
127
128
128
/// A marker trait representing types where a shared reference is considered
129
- /// recover safe.
129
+ /// unwind safe.
130
130
///
131
131
/// This trait is namely not implemented by `UnsafeCell`, the root of all
132
132
/// interior mutability.
@@ -136,31 +136,31 @@ impl<T: UnwindSafe> RecoverSafe for T {}
136
136
#[ stable( feature = "catch_unwind" , since = "1.9.0" ) ]
137
137
#[ rustc_on_unimplemented = "the type {Self} contains interior mutability \
138
138
and a reference may not be safely transferrable \
139
- across a recover boundary"]
139
+ across a catch_unwind boundary"]
140
140
pub trait RefUnwindSafe { }
141
141
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.
143
143
///
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
147
147
/// 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
149
149
/// 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.
151
151
///
152
152
/// # Examples
153
153
///
154
154
/// 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:
156
156
///
157
157
/// ```
158
158
/// use std::panic::{self, AssertUnwindSafe};
159
159
///
160
160
/// let mut variable = 4;
161
161
///
162
162
/// // 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.
164
164
///
165
165
/// // panic::catch_unwind(|| {
166
166
/// // variable += 3;
@@ -239,7 +239,7 @@ impl<T> UnwindSafe for AssertUnwindSafe<T> {}
239
239
impl < T > UnwindSafe for AssertRecoverSafe < T > { }
240
240
241
241
// 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
243
243
// impl up one level to Arc/Rc itself
244
244
#[ stable( feature = "catch_unwind" , since = "1.9.0" ) ]
245
245
impl < T : RefUnwindSafe + ?Sized > UnwindSafe for Rc < T > { }
@@ -352,9 +352,9 @@ impl<R, F: FnOnce() -> R> FnOnce<()> for AssertRecoverSafe<F> {
352
352
/// that all captured variables are safe to cross this boundary. The purpose of
353
353
/// this bound is to encode the concept of [exception safety][rfc] in the type
354
354
/// 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
356
356
/// 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
358
358
/// safe.
359
359
///
360
360
/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
0 commit comments