Auto merge of #84662 - dtolnay:unwindsafe, r=Amanieu
Move UnwindSafe, RefUnwindSafe, AssertUnwindSafe to core
They were previously only available in std::panic, not core::panic.
- https://doc.rust-lang.org/1.51.0/std/panic/trait.UnwindSafe.html
- https://doc.rust-lang.org/1.51.0/std/panic/trait.RefUnwindSafe.html
- https://doc.rust-lang.org/1.51.0/std/panic/struct.AssertUnwindSafe.html
Where this is relevant: trait objects! Inside a `#![no_std]` library it's otherwise impossible to have a struct holding a trait object, and at the same time can be used from downstream std crates in a way that doesn't interfere with catch_unwind.
```rust
// common library
#![no_std]
pub struct Thing {
pub(crate) x: &'static (dyn SomeTrait + Send + Sync),
}
pub(crate) trait SomeTrait {...}
```
```rust
// downstream application
fn main() {
let thing: library::Thing = ...;
let _ = std::panic::catch_unwind(|| { let _ = thing; }); // does not work :(
}
```
See a4131708e2/src/gradient.rs (L7-L15) for a real life example of needing to work around this problem. In particular that workaround would not even be viable if implementors of the trait were provided externally by a caller, as the `feature = "std"` would become non-additive in that case.
What happens without the UnwindSafe constraints:
```rust
fn main() {
let gradient = colorous::VIRIDIS;
let _ = std::panic::catch_unwind(|| { let _ = gradient; });
}
```
```console
error[E0277]: the type `(dyn colorous::gradient::EvalGradient + Send + Sync + 'static)` may contain interior mutability and a reference may not be safely transferrable across a catch_unwind boundary
--> src/main.rs:3:13
|
3 | let _ = std::panic::catch_unwind(|| { let _ = gradient; });
| ^^^^^^^^^^^^^^^^^^^^^^^^ `(dyn colorous::gradient::EvalGradient + Send + Sync + 'static)` may contain interior mutability and a reference may not be safely transferrable across a catch_unwind boundary
|
::: .rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/std/src/panic.rs:430:40
|
430 | pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> {
| ---------- required by this bound in `catch_unwind`
|
= help: within `Gradient`, the trait `RefUnwindSafe` is not implemented for `(dyn colorous::gradient::EvalGradient + Send + Sync + 'static)`
= note: required because it appears within the type `&'static (dyn colorous::gradient::EvalGradient + Send + Sync + 'static)`
= note: required because it appears within the type `Gradient`
= note: required because of the requirements on the impl of `UnwindSafe` for `&Gradient`
= note: required because it appears within the type `[closure@src/main.rs:3:38: 3:62]`
```
This commit is contained in:
bors
commit
f381e77d35
7 changed files with 662 additions and 638 deletions
|
|
@ -262,6 +262,7 @@ use core::marker::{self, PhantomData, Unpin, Unsize};
|
|||
use core::mem::size_of_val;
|
||||
use core::mem::{self, align_of_val_raw, forget};
|
||||
use core::ops::{CoerceUnsized, Deref, DispatchFromDyn, Receiver};
|
||||
use core::panic::{RefUnwindSafe, UnwindSafe};
|
||||
#[cfg(not(no_global_oom_handling))]
|
||||
use core::pin::Pin;
|
||||
use core::ptr::{self, NonNull};
|
||||
|
|
@ -314,6 +315,9 @@ impl<T: ?Sized> !marker::Send for Rc<T> {}
|
|||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
impl<T: ?Sized> !marker::Sync for Rc<T> {}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Rc<T> {}
|
||||
|
||||
#[unstable(feature = "coerce_unsized", issue = "27732")]
|
||||
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Rc<U>> for Rc<T> {}
|
||||
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ use core::marker::{PhantomData, Unpin, Unsize};
|
|||
use core::mem::size_of_val;
|
||||
use core::mem::{self, align_of_val_raw};
|
||||
use core::ops::{CoerceUnsized, Deref, DispatchFromDyn, Receiver};
|
||||
use core::panic::{RefUnwindSafe, UnwindSafe};
|
||||
use core::pin::Pin;
|
||||
use core::ptr::{self, NonNull};
|
||||
#[cfg(not(no_global_oom_handling))]
|
||||
|
|
@ -240,6 +241,9 @@ unsafe impl<T: ?Sized + Sync + Send> Send for Arc<T> {}
|
|||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
unsafe impl<T: ?Sized + Sync + Send> Sync for Arc<T> {}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Arc<T> {}
|
||||
|
||||
#[unstable(feature = "coerce_unsized", issue = "27732")]
|
||||
impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Arc<U>> for Arc<T> {}
|
||||
|
||||
|
|
|
|||
|
|
@ -2,8 +2,18 @@
|
|||
|
||||
#![stable(feature = "core_panic_info", since = "1.41.0")]
|
||||
|
||||
mod location;
|
||||
mod panic_info;
|
||||
mod unwind_safe;
|
||||
|
||||
use crate::any::Any;
|
||||
use crate::fmt;
|
||||
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub use self::location::Location;
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub use self::panic_info::PanicInfo;
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
pub use self::unwind_safe::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe};
|
||||
|
||||
#[doc(hidden)]
|
||||
#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
|
||||
|
|
@ -39,334 +49,6 @@ pub macro panic_2021 {
|
|||
),
|
||||
}
|
||||
|
||||
/// A struct providing information about a panic.
|
||||
///
|
||||
/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`]
|
||||
/// function.
|
||||
///
|
||||
/// [`set_hook`]: ../../std/panic/fn.set_hook.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
|
||||
/// println!("panic occurred: {:?}", s);
|
||||
/// } else {
|
||||
/// println!("panic occurred");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[lang = "panic_info"]
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
#[derive(Debug)]
|
||||
pub struct PanicInfo<'a> {
|
||||
payload: &'a (dyn Any + Send),
|
||||
message: Option<&'a fmt::Arguments<'a>>,
|
||||
location: &'a Location<'a>,
|
||||
}
|
||||
|
||||
impl<'a> PanicInfo<'a> {
|
||||
#[unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
#[doc(hidden)]
|
||||
#[inline]
|
||||
pub fn internal_constructor(
|
||||
message: Option<&'a fmt::Arguments<'a>>,
|
||||
location: &'a Location<'a>,
|
||||
) -> Self {
|
||||
struct NoPayload;
|
||||
PanicInfo { location, message, payload: &NoPayload }
|
||||
}
|
||||
|
||||
#[unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
#[doc(hidden)]
|
||||
#[inline]
|
||||
pub fn set_payload(&mut self, info: &'a (dyn Any + Send)) {
|
||||
self.payload = info;
|
||||
}
|
||||
|
||||
/// Returns the payload associated with the panic.
|
||||
///
|
||||
/// This will commonly, but not always, be a `&'static str` or [`String`].
|
||||
///
|
||||
/// [`String`]: ../../std/string/struct.String.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
|
||||
/// println!("panic occurred: {:?}", s);
|
||||
/// } else {
|
||||
/// println!("panic occurred");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn payload(&self) -> &(dyn Any + Send) {
|
||||
self.payload
|
||||
}
|
||||
|
||||
/// If the `panic!` macro from the `core` crate (not from `std`)
|
||||
/// was used with a formatting string and some additional arguments,
|
||||
/// returns that message ready to be used for example with [`fmt::write`]
|
||||
#[unstable(feature = "panic_info_message", issue = "66745")]
|
||||
pub fn message(&self) -> Option<&fmt::Arguments<'_>> {
|
||||
self.message
|
||||
}
|
||||
|
||||
/// Returns information about the location from which the panic originated,
|
||||
/// if available.
|
||||
///
|
||||
/// This method will currently always return [`Some`], but this may change
|
||||
/// in future versions.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}' at line {}",
|
||||
/// location.file(),
|
||||
/// location.line(),
|
||||
/// );
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn location(&self) -> Option<&Location<'_>> {
|
||||
// NOTE: If this is changed to sometimes return None,
|
||||
// deal with that case in std::panicking::default_hook and std::panicking::begin_panic_fmt.
|
||||
Some(&self.location)
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "panic_hook_display", since = "1.26.0")]
|
||||
impl fmt::Display for PanicInfo<'_> {
|
||||
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
formatter.write_str("panicked at ")?;
|
||||
if let Some(message) = self.message {
|
||||
write!(formatter, "'{}', ", message)?
|
||||
} else if let Some(payload) = self.payload.downcast_ref::<&'static str>() {
|
||||
write!(formatter, "'{}', ", payload)?
|
||||
}
|
||||
// NOTE: we cannot use downcast_ref::<String>() here
|
||||
// since String is not available in libcore!
|
||||
// The payload is a String when `std::panic!` is called with multiple arguments,
|
||||
// but in that case the message is also available.
|
||||
|
||||
self.location.fmt(formatter)
|
||||
}
|
||||
}
|
||||
|
||||
/// A struct containing information about the location of a panic.
|
||||
///
|
||||
/// This structure is created by [`PanicInfo::location()`].
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}' at line {}", location.file(), location.line());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
///
|
||||
/// # Comparisons
|
||||
///
|
||||
/// Comparisons for equality and ordering are made in file, line, then column priority.
|
||||
/// Files are compared as strings, not `Path`, which could be unexpected.
|
||||
/// See [`Location::file`]'s documentation for more discussion.
|
||||
#[lang = "panic_location"]
|
||||
#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub struct Location<'a> {
|
||||
file: &'a str,
|
||||
line: u32,
|
||||
col: u32,
|
||||
}
|
||||
|
||||
impl<'a> Location<'a> {
|
||||
/// Returns the source location of the caller of this function. If that function's caller is
|
||||
/// annotated then its call location will be returned, and so on up the stack to the first call
|
||||
/// within a non-tracked function body.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::panic::Location;
|
||||
///
|
||||
/// /// Returns the [`Location`] at which it is called.
|
||||
/// #[track_caller]
|
||||
/// fn get_caller_location() -> &'static Location<'static> {
|
||||
/// Location::caller()
|
||||
/// }
|
||||
///
|
||||
/// /// Returns a [`Location`] from within this function's definition.
|
||||
/// fn get_just_one_location() -> &'static Location<'static> {
|
||||
/// get_caller_location()
|
||||
/// }
|
||||
///
|
||||
/// let fixed_location = get_just_one_location();
|
||||
/// assert_eq!(fixed_location.file(), file!());
|
||||
/// assert_eq!(fixed_location.line(), 14);
|
||||
/// assert_eq!(fixed_location.column(), 5);
|
||||
///
|
||||
/// // running the same untracked function in a different location gives us the same result
|
||||
/// let second_fixed_location = get_just_one_location();
|
||||
/// assert_eq!(fixed_location.file(), second_fixed_location.file());
|
||||
/// assert_eq!(fixed_location.line(), second_fixed_location.line());
|
||||
/// assert_eq!(fixed_location.column(), second_fixed_location.column());
|
||||
///
|
||||
/// let this_location = get_caller_location();
|
||||
/// assert_eq!(this_location.file(), file!());
|
||||
/// assert_eq!(this_location.line(), 28);
|
||||
/// assert_eq!(this_location.column(), 21);
|
||||
///
|
||||
/// // running the tracked function in a different location produces a different value
|
||||
/// let another_location = get_caller_location();
|
||||
/// assert_eq!(this_location.file(), another_location.file());
|
||||
/// assert_ne!(this_location.line(), another_location.line());
|
||||
/// assert_ne!(this_location.column(), another_location.column());
|
||||
/// ```
|
||||
#[stable(feature = "track_caller", since = "1.46.0")]
|
||||
#[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
|
||||
#[track_caller]
|
||||
pub const fn caller() -> &'static Location<'static> {
|
||||
crate::intrinsics::caller_location()
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a> Location<'a> {
|
||||
#![unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
#[doc(hidden)]
|
||||
pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self {
|
||||
Location { file, line, col }
|
||||
}
|
||||
|
||||
/// Returns the name of the source file from which the panic originated.
|
||||
///
|
||||
/// # `&str`, not `&Path`
|
||||
///
|
||||
/// The returned name refers to a source path on the compiling system, but it isn't valid to
|
||||
/// represent this directly as a `&Path`. The compiled code may run on a different system with
|
||||
/// a different `Path` implementation than the system providing the contents and this library
|
||||
/// does not currently have a different "host path" type.
|
||||
///
|
||||
/// The most surprising behavior occurs when "the same" file is reachable via multiple paths in
|
||||
/// the module system (usually using the `#[path = "..."]` attribute or similar), which can
|
||||
/// cause what appears to be identical code to return differing values from this function.
|
||||
///
|
||||
/// # Cross-compilation
|
||||
///
|
||||
/// This value is not suitable for passing to `Path::new` or similar constructors when the host
|
||||
/// platform and target platform differ.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}'", location.file());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn file(&self) -> &str {
|
||||
self.file
|
||||
}
|
||||
|
||||
/// Returns the line number from which the panic originated.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred at line {}", location.line());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn line(&self) -> u32 {
|
||||
self.line
|
||||
}
|
||||
|
||||
/// Returns the column from which the panic originated.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred at column {}", location.column());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_col", since = "1.25.0")]
|
||||
pub fn column(&self) -> u32 {
|
||||
self.col
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "panic_hook_display", since = "1.26.0")]
|
||||
impl fmt::Display for Location<'_> {
|
||||
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(formatter, "{}:{}:{}", self.file, self.line, self.col)
|
||||
}
|
||||
}
|
||||
|
||||
/// An internal trait used by libstd to pass data from libstd to `panic_unwind`
|
||||
/// and other panic runtimes. Not intended to be stabilized any time soon, do
|
||||
/// not use.
|
||||
|
|
|
|||
189
library/core/src/panic/location.rs
Normal file
189
library/core/src/panic/location.rs
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
use crate::fmt;
|
||||
|
||||
/// A struct containing information about the location of a panic.
|
||||
///
|
||||
/// This structure is created by [`PanicInfo::location()`].
|
||||
///
|
||||
/// [`PanicInfo::location()`]: crate::panic::PanicInfo::location
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}' at line {}", location.file(), location.line());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
///
|
||||
/// # Comparisons
|
||||
///
|
||||
/// Comparisons for equality and ordering are made in file, line, then column priority.
|
||||
/// Files are compared as strings, not `Path`, which could be unexpected.
|
||||
/// See [`Location::file`]'s documentation for more discussion.
|
||||
#[lang = "panic_location"]
|
||||
#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub struct Location<'a> {
|
||||
file: &'a str,
|
||||
line: u32,
|
||||
col: u32,
|
||||
}
|
||||
|
||||
impl<'a> Location<'a> {
|
||||
/// Returns the source location of the caller of this function. If that function's caller is
|
||||
/// annotated then its call location will be returned, and so on up the stack to the first call
|
||||
/// within a non-tracked function body.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::panic::Location;
|
||||
///
|
||||
/// /// Returns the [`Location`] at which it is called.
|
||||
/// #[track_caller]
|
||||
/// fn get_caller_location() -> &'static Location<'static> {
|
||||
/// Location::caller()
|
||||
/// }
|
||||
///
|
||||
/// /// Returns a [`Location`] from within this function's definition.
|
||||
/// fn get_just_one_location() -> &'static Location<'static> {
|
||||
/// get_caller_location()
|
||||
/// }
|
||||
///
|
||||
/// let fixed_location = get_just_one_location();
|
||||
/// assert_eq!(fixed_location.file(), file!());
|
||||
/// assert_eq!(fixed_location.line(), 14);
|
||||
/// assert_eq!(fixed_location.column(), 5);
|
||||
///
|
||||
/// // running the same untracked function in a different location gives us the same result
|
||||
/// let second_fixed_location = get_just_one_location();
|
||||
/// assert_eq!(fixed_location.file(), second_fixed_location.file());
|
||||
/// assert_eq!(fixed_location.line(), second_fixed_location.line());
|
||||
/// assert_eq!(fixed_location.column(), second_fixed_location.column());
|
||||
///
|
||||
/// let this_location = get_caller_location();
|
||||
/// assert_eq!(this_location.file(), file!());
|
||||
/// assert_eq!(this_location.line(), 28);
|
||||
/// assert_eq!(this_location.column(), 21);
|
||||
///
|
||||
/// // running the tracked function in a different location produces a different value
|
||||
/// let another_location = get_caller_location();
|
||||
/// assert_eq!(this_location.file(), another_location.file());
|
||||
/// assert_ne!(this_location.line(), another_location.line());
|
||||
/// assert_ne!(this_location.column(), another_location.column());
|
||||
/// ```
|
||||
#[stable(feature = "track_caller", since = "1.46.0")]
|
||||
#[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
|
||||
#[track_caller]
|
||||
pub const fn caller() -> &'static Location<'static> {
|
||||
crate::intrinsics::caller_location()
|
||||
}
|
||||
|
||||
/// Returns the name of the source file from which the panic originated.
|
||||
///
|
||||
/// # `&str`, not `&Path`
|
||||
///
|
||||
/// The returned name refers to a source path on the compiling system, but it isn't valid to
|
||||
/// represent this directly as a `&Path`. The compiled code may run on a different system with
|
||||
/// a different `Path` implementation than the system providing the contents and this library
|
||||
/// does not currently have a different "host path" type.
|
||||
///
|
||||
/// The most surprising behavior occurs when "the same" file is reachable via multiple paths in
|
||||
/// the module system (usually using the `#[path = "..."]` attribute or similar), which can
|
||||
/// cause what appears to be identical code to return differing values from this function.
|
||||
///
|
||||
/// # Cross-compilation
|
||||
///
|
||||
/// This value is not suitable for passing to `Path::new` or similar constructors when the host
|
||||
/// platform and target platform differ.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}'", location.file());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn file(&self) -> &str {
|
||||
self.file
|
||||
}
|
||||
|
||||
/// Returns the line number from which the panic originated.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred at line {}", location.line());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn line(&self) -> u32 {
|
||||
self.line
|
||||
}
|
||||
|
||||
/// Returns the column from which the panic originated.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred at column {}", location.column());
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_col", since = "1.25.0")]
|
||||
pub fn column(&self) -> u32 {
|
||||
self.col
|
||||
}
|
||||
}
|
||||
|
||||
#[unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
impl<'a> Location<'a> {
|
||||
#[doc(hidden)]
|
||||
pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self {
|
||||
Location { file, line, col }
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "panic_hook_display", since = "1.26.0")]
|
||||
impl fmt::Display for Location<'_> {
|
||||
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(formatter, "{}:{}:{}", self.file, self.line, self.col)
|
||||
}
|
||||
}
|
||||
145
library/core/src/panic/panic_info.rs
Normal file
145
library/core/src/panic/panic_info.rs
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
use crate::any::Any;
|
||||
use crate::fmt;
|
||||
use crate::panic::Location;
|
||||
|
||||
/// A struct providing information about a panic.
|
||||
///
|
||||
/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`]
|
||||
/// function.
|
||||
///
|
||||
/// [`set_hook`]: ../../std/panic/fn.set_hook.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
|
||||
/// println!("panic occurred: {:?}", s);
|
||||
/// } else {
|
||||
/// println!("panic occurred");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[lang = "panic_info"]
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
#[derive(Debug)]
|
||||
pub struct PanicInfo<'a> {
|
||||
payload: &'a (dyn Any + Send),
|
||||
message: Option<&'a fmt::Arguments<'a>>,
|
||||
location: &'a Location<'a>,
|
||||
}
|
||||
|
||||
impl<'a> PanicInfo<'a> {
|
||||
#[unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
#[doc(hidden)]
|
||||
#[inline]
|
||||
pub fn internal_constructor(
|
||||
message: Option<&'a fmt::Arguments<'a>>,
|
||||
location: &'a Location<'a>,
|
||||
) -> Self {
|
||||
struct NoPayload;
|
||||
PanicInfo { location, message, payload: &NoPayload }
|
||||
}
|
||||
|
||||
#[unstable(
|
||||
feature = "panic_internals",
|
||||
reason = "internal details of the implementation of the `panic!` and related macros",
|
||||
issue = "none"
|
||||
)]
|
||||
#[doc(hidden)]
|
||||
#[inline]
|
||||
pub fn set_payload(&mut self, info: &'a (dyn Any + Send)) {
|
||||
self.payload = info;
|
||||
}
|
||||
|
||||
/// Returns the payload associated with the panic.
|
||||
///
|
||||
/// This will commonly, but not always, be a `&'static str` or [`String`].
|
||||
///
|
||||
/// [`String`]: ../../std/string/struct.String.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
|
||||
/// println!("panic occurred: {:?}", s);
|
||||
/// } else {
|
||||
/// println!("panic occurred");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn payload(&self) -> &(dyn Any + Send) {
|
||||
self.payload
|
||||
}
|
||||
|
||||
/// If the `panic!` macro from the `core` crate (not from `std`)
|
||||
/// was used with a formatting string and some additional arguments,
|
||||
/// returns that message ready to be used for example with [`fmt::write`]
|
||||
#[unstable(feature = "panic_info_message", issue = "66745")]
|
||||
pub fn message(&self) -> Option<&fmt::Arguments<'_>> {
|
||||
self.message
|
||||
}
|
||||
|
||||
/// Returns information about the location from which the panic originated,
|
||||
/// if available.
|
||||
///
|
||||
/// This method will currently always return [`Some`], but this may change
|
||||
/// in future versions.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```should_panic
|
||||
/// use std::panic;
|
||||
///
|
||||
/// panic::set_hook(Box::new(|panic_info| {
|
||||
/// if let Some(location) = panic_info.location() {
|
||||
/// println!("panic occurred in file '{}' at line {}",
|
||||
/// location.file(),
|
||||
/// location.line(),
|
||||
/// );
|
||||
/// } else {
|
||||
/// println!("panic occurred but can't get location information...");
|
||||
/// }
|
||||
/// }));
|
||||
///
|
||||
/// panic!("Normal panic");
|
||||
/// ```
|
||||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub fn location(&self) -> Option<&Location<'_>> {
|
||||
// NOTE: If this is changed to sometimes return None,
|
||||
// deal with that case in std::panicking::default_hook and std::panicking::begin_panic_fmt.
|
||||
Some(&self.location)
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "panic_hook_display", since = "1.26.0")]
|
||||
impl fmt::Display for PanicInfo<'_> {
|
||||
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
formatter.write_str("panicked at ")?;
|
||||
if let Some(message) = self.message {
|
||||
write!(formatter, "'{}', ", message)?
|
||||
} else if let Some(payload) = self.payload.downcast_ref::<&'static str>() {
|
||||
write!(formatter, "'{}', ", payload)?
|
||||
}
|
||||
// NOTE: we cannot use downcast_ref::<String>() here
|
||||
// since String is not available in libcore!
|
||||
// The payload is a String when `std::panic!` is called with multiple arguments,
|
||||
// but in that case the message is also available.
|
||||
|
||||
self.location.fmt(formatter)
|
||||
}
|
||||
}
|
||||
305
library/core/src/panic/unwind_safe.rs
Normal file
305
library/core/src/panic/unwind_safe.rs
Normal file
|
|
@ -0,0 +1,305 @@
|
|||
use crate::cell::UnsafeCell;
|
||||
use crate::fmt;
|
||||
use crate::future::Future;
|
||||
use crate::ops::{Deref, DerefMut};
|
||||
use crate::pin::Pin;
|
||||
use crate::ptr::{NonNull, Unique};
|
||||
use crate::stream::Stream;
|
||||
use crate::task::{Context, Poll};
|
||||
|
||||
/// 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 [`catch_unwind`]
|
||||
/// boundary with no fear of unwind safety.
|
||||
///
|
||||
/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html
|
||||
///
|
||||
/// ## 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
|
||||
/// anticipated, and has the possibility of causing subtle bugs through a
|
||||
/// combination of two critical 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 `catch_unwind` function in this
|
||||
/// module. Additionally, even if an invariant is witnessed, it typically isn't a
|
||||
/// 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 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 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 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 `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 `catch_unwind` (catching a
|
||||
/// panic). This trait is an auto trait, so it is automatically implemented for
|
||||
/// 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 `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**
|
||||
/// 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 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?
|
||||
///
|
||||
/// It is not intended that most types or functions need to worry about this trait.
|
||||
/// 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 can be used to force this trait to be
|
||||
/// implemented for any closed over variables passed to `catch_unwind`.
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
#[cfg_attr(not(test), rustc_diagnostic_item = "unwind_safe_trait")]
|
||||
#[rustc_on_unimplemented(
|
||||
message = "the type `{Self}` may not be safely transferred across an unwind boundary",
|
||||
label = "`{Self}` may not be safely transferred across an unwind boundary"
|
||||
)]
|
||||
pub auto trait UnwindSafe {}
|
||||
|
||||
/// A marker trait representing types where a shared reference is considered
|
||||
/// unwind safe.
|
||||
///
|
||||
/// This trait is namely not implemented by [`UnsafeCell`], the root of all
|
||||
/// interior mutability.
|
||||
///
|
||||
/// This is a "helper marker trait" used to provide impl blocks for the
|
||||
/// [`UnwindSafe`] trait, for more information see that documentation.
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
#[cfg_attr(not(test), rustc_diagnostic_item = "ref_unwind_safe_trait")]
|
||||
#[rustc_on_unimplemented(
|
||||
message = "the type `{Self}` may contain interior mutability and a reference may not be safely \
|
||||
transferrable across a catch_unwind boundary",
|
||||
label = "`{Self}` may contain interior mutability and a reference may not be safely \
|
||||
transferrable across a catch_unwind boundary"
|
||||
)]
|
||||
pub auto trait RefUnwindSafe {}
|
||||
|
||||
/// A simple wrapper around a type to assert that it is unwind safe.
|
||||
///
|
||||
/// 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
|
||||
/// might not be the case, however, that this is actually a problem due to the
|
||||
/// 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 unwind safe.
|
||||
///
|
||||
/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// One way to use `AssertUnwindSafe` is to assert that the entire closure
|
||||
/// 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 unwind safe by default.
|
||||
///
|
||||
/// // panic::catch_unwind(|| {
|
||||
/// // variable += 3;
|
||||
/// // });
|
||||
///
|
||||
/// // This, however, will compile due to the `AssertUnwindSafe` wrapper
|
||||
/// let result = panic::catch_unwind(AssertUnwindSafe(|| {
|
||||
/// variable += 3;
|
||||
/// }));
|
||||
/// // ...
|
||||
/// ```
|
||||
///
|
||||
/// Wrapping the entire closure amounts to a blanket assertion that all captured
|
||||
/// variables are unwind safe. This has the downside that if new captures are
|
||||
/// added in the future, they will also be considered unwind safe. Therefore,
|
||||
/// you may prefer to just wrap individual captures, as shown below. This is
|
||||
/// more annotation, but it ensures that if a new capture is added which is not
|
||||
/// unwind safe, you will get a compilation error at that time, which will
|
||||
/// allow you to consider whether that new capture in fact represent a bug or
|
||||
/// not.
|
||||
///
|
||||
/// ```
|
||||
/// use std::panic::{self, AssertUnwindSafe};
|
||||
///
|
||||
/// let mut variable = 4;
|
||||
/// let other_capture = 3;
|
||||
///
|
||||
/// let result = {
|
||||
/// let mut wrapper = AssertUnwindSafe(&mut variable);
|
||||
/// panic::catch_unwind(move || {
|
||||
/// **wrapper += other_capture;
|
||||
/// })
|
||||
/// };
|
||||
/// // ...
|
||||
/// ```
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
pub struct AssertUnwindSafe<T>(#[stable(feature = "catch_unwind", since = "1.9.0")] pub T);
|
||||
|
||||
// Implementations of the `UnwindSafe` trait:
|
||||
//
|
||||
// * By default everything is unwind safe
|
||||
// * pointers T contains mutability of some form are not unwind safe
|
||||
// * Unique, an owning pointer, lifts an implementation
|
||||
// * Types like Mutex/RwLock which are explicitly poisoned are unwind safe
|
||||
// * Our custom AssertUnwindSafe wrapper is indeed unwind safe
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> !UnwindSafe for &mut T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for &T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for *const T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for *mut T {}
|
||||
#[unstable(feature = "ptr_internals", issue = "none")]
|
||||
impl<T: UnwindSafe + ?Sized> UnwindSafe for Unique<T> {}
|
||||
#[stable(feature = "nonnull", since = "1.25.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for NonNull<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> UnwindSafe for AssertUnwindSafe<T> {}
|
||||
|
||||
// Pretty simple implementations for the `RefUnwindSafe` marker trait,
|
||||
// basically just saying that `UnsafeCell` is the
|
||||
// only thing which doesn't implement it (which then transitively applies to
|
||||
// everything else).
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> !RefUnwindSafe for UnsafeCell<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> RefUnwindSafe for AssertUnwindSafe<T> {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicIsize {}
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicI8 {}
|
||||
#[cfg(target_has_atomic_load_store = "16")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicI16 {}
|
||||
#[cfg(target_has_atomic_load_store = "32")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicI32 {}
|
||||
#[cfg(target_has_atomic_load_store = "64")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicI64 {}
|
||||
#[cfg(target_has_atomic_load_store = "128")]
|
||||
#[unstable(feature = "integer_atomics", issue = "32976")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicI128 {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicUsize {}
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicU8 {}
|
||||
#[cfg(target_has_atomic_load_store = "16")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicU16 {}
|
||||
#[cfg(target_has_atomic_load_store = "32")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicU32 {}
|
||||
#[cfg(target_has_atomic_load_store = "64")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicU64 {}
|
||||
#[cfg(target_has_atomic_load_store = "128")]
|
||||
#[unstable(feature = "integer_atomics", issue = "32976")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicU128 {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for crate::sync::atomic::AtomicBool {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl<T> RefUnwindSafe for crate::sync::atomic::AtomicPtr<T> {}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> Deref for AssertUnwindSafe<T> {
|
||||
type Target = T;
|
||||
|
||||
fn deref(&self) -> &T {
|
||||
&self.0
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> DerefMut for AssertUnwindSafe<T> {
|
||||
fn deref_mut(&mut self) -> &mut T {
|
||||
&mut self.0
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<R, F: FnOnce() -> R> FnOnce<()> for AssertUnwindSafe<F> {
|
||||
type Output = R;
|
||||
|
||||
extern "rust-call" fn call_once(self, _args: ()) -> R {
|
||||
(self.0)()
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "std_debug", since = "1.16.0")]
|
||||
impl<T: fmt::Debug> fmt::Debug for AssertUnwindSafe<T> {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.debug_tuple("AssertUnwindSafe").field(&self.0).finish()
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "futures_api", since = "1.36.0")]
|
||||
impl<F: Future> Future for AssertUnwindSafe<F> {
|
||||
type Output = F::Output;
|
||||
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
|
||||
// SAFETY: pin projection. AssertUnwindSafe follows structural pinning.
|
||||
let pinned_field = unsafe { Pin::map_unchecked_mut(self, |x| &mut x.0) };
|
||||
F::poll(pinned_field, cx)
|
||||
}
|
||||
}
|
||||
|
||||
#[unstable(feature = "async_stream", issue = "79024")]
|
||||
impl<S: Stream> Stream for AssertUnwindSafe<S> {
|
||||
type Item = S::Item;
|
||||
|
||||
fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<S::Item>> {
|
||||
// SAFETY: pin projection. AssertUnwindSafe follows structural pinning.
|
||||
unsafe { self.map_unchecked_mut(|x| &mut x.0) }.poll_next(cx)
|
||||
}
|
||||
|
||||
fn size_hint(&self) -> (usize, Option<usize>) {
|
||||
self.0.size_hint()
|
||||
}
|
||||
}
|
||||
|
|
@ -3,19 +3,9 @@
|
|||
#![stable(feature = "std_panic", since = "1.9.0")]
|
||||
|
||||
use crate::any::Any;
|
||||
use crate::cell::UnsafeCell;
|
||||
use crate::collections;
|
||||
use crate::fmt;
|
||||
use crate::future::Future;
|
||||
use crate::ops::{Deref, DerefMut};
|
||||
use crate::panicking;
|
||||
use crate::pin::Pin;
|
||||
use crate::ptr::{NonNull, Unique};
|
||||
use crate::rc::Rc;
|
||||
use crate::stream::Stream;
|
||||
use crate::sync::atomic;
|
||||
use crate::sync::{Arc, Mutex, RwLock};
|
||||
use crate::task::{Context, Poll};
|
||||
use crate::sync::{Mutex, RwLock};
|
||||
use crate::thread::Result;
|
||||
|
||||
#[doc(hidden)]
|
||||
|
|
@ -45,6 +35,9 @@ pub use crate::panicking::{set_hook, take_hook};
|
|||
#[stable(feature = "panic_hooks", since = "1.10.0")]
|
||||
pub use core::panic::{Location, PanicInfo};
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
pub use core::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe};
|
||||
|
||||
/// Panic the current thread with the given message as the panic payload.
|
||||
///
|
||||
/// The message can be of any (`Any + Send`) type, not just strings.
|
||||
|
|
@ -60,259 +53,16 @@ pub fn panic_any<M: 'static + Any + Send>(msg: M) -> ! {
|
|||
crate::panicking::begin_panic(msg);
|
||||
}
|
||||
|
||||
/// 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 [`catch_unwind`]
|
||||
/// boundary with no fear of unwind 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
|
||||
/// anticipated, and has the possibility of causing subtle bugs through a
|
||||
/// combination of two critical 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 `catch_unwind` function in this
|
||||
/// module. Additionally, even if an invariant is witnessed, it typically isn't a
|
||||
/// 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 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 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 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 `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 `catch_unwind` (catching a
|
||||
/// panic). This trait is an auto trait, so it is automatically implemented for
|
||||
/// 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 `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**
|
||||
/// 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 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?
|
||||
///
|
||||
/// It is not intended that most types or functions need to worry about this trait.
|
||||
/// 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 can be used to force this trait to be
|
||||
/// implemented for any closed over variables passed to `catch_unwind`.
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
#[cfg_attr(not(test), rustc_diagnostic_item = "unwind_safe_trait")]
|
||||
#[rustc_on_unimplemented(
|
||||
message = "the type `{Self}` may not be safely transferred across an unwind boundary",
|
||||
label = "`{Self}` may not be safely transferred across an unwind boundary"
|
||||
)]
|
||||
pub auto trait UnwindSafe {}
|
||||
|
||||
/// A marker trait representing types where a shared reference is considered
|
||||
/// unwind safe.
|
||||
///
|
||||
/// This trait is namely not implemented by [`UnsafeCell`], the root of all
|
||||
/// interior mutability.
|
||||
///
|
||||
/// This is a "helper marker trait" used to provide impl blocks for the
|
||||
/// [`UnwindSafe`] trait, for more information see that documentation.
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
#[cfg_attr(not(test), rustc_diagnostic_item = "ref_unwind_safe_trait")]
|
||||
#[rustc_on_unimplemented(
|
||||
message = "the type `{Self}` may contain interior mutability and a reference may not be safely \
|
||||
transferrable across a catch_unwind boundary",
|
||||
label = "`{Self}` may contain interior mutability and a reference may not be safely \
|
||||
transferrable across a catch_unwind boundary"
|
||||
)]
|
||||
pub auto trait RefUnwindSafe {}
|
||||
|
||||
/// A simple wrapper around a type to assert that it is unwind safe.
|
||||
///
|
||||
/// 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
|
||||
/// might not be the case, however, that this is actually a problem due to the
|
||||
/// 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 unwind safe.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// One way to use `AssertUnwindSafe` is to assert that the entire closure
|
||||
/// 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 unwind safe by default.
|
||||
///
|
||||
/// // panic::catch_unwind(|| {
|
||||
/// // variable += 3;
|
||||
/// // });
|
||||
///
|
||||
/// // This, however, will compile due to the `AssertUnwindSafe` wrapper
|
||||
/// let result = panic::catch_unwind(AssertUnwindSafe(|| {
|
||||
/// variable += 3;
|
||||
/// }));
|
||||
/// // ...
|
||||
/// ```
|
||||
///
|
||||
/// Wrapping the entire closure amounts to a blanket assertion that all captured
|
||||
/// variables are unwind safe. This has the downside that if new captures are
|
||||
/// added in the future, they will also be considered unwind safe. Therefore,
|
||||
/// you may prefer to just wrap individual captures, as shown below. This is
|
||||
/// more annotation, but it ensures that if a new capture is added which is not
|
||||
/// unwind safe, you will get a compilation error at that time, which will
|
||||
/// allow you to consider whether that new capture in fact represent a bug or
|
||||
/// not.
|
||||
///
|
||||
/// ```
|
||||
/// use std::panic::{self, AssertUnwindSafe};
|
||||
///
|
||||
/// let mut variable = 4;
|
||||
/// let other_capture = 3;
|
||||
///
|
||||
/// let result = {
|
||||
/// let mut wrapper = AssertUnwindSafe(&mut variable);
|
||||
/// panic::catch_unwind(move || {
|
||||
/// **wrapper += other_capture;
|
||||
/// })
|
||||
/// };
|
||||
/// // ...
|
||||
/// ```
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
pub struct AssertUnwindSafe<T>(#[stable(feature = "catch_unwind", since = "1.9.0")] pub T);
|
||||
|
||||
// Implementations of the `UnwindSafe` trait:
|
||||
//
|
||||
// * By default everything is unwind safe
|
||||
// * pointers T contains mutability of some form are not unwind safe
|
||||
// * Unique, an owning pointer, lifts an implementation
|
||||
// * Types like Mutex/RwLock which are explicitly poisoned are unwind safe
|
||||
// * Our custom AssertUnwindSafe wrapper is indeed unwind safe
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> !UnwindSafe for &mut T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for &T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for *const T {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for *mut T {}
|
||||
#[unstable(feature = "ptr_internals", issue = "none")]
|
||||
impl<T: UnwindSafe + ?Sized> UnwindSafe for Unique<T> {}
|
||||
#[stable(feature = "nonnull", since = "1.25.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for NonNull<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> UnwindSafe for Mutex<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> UnwindSafe for RwLock<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> UnwindSafe for AssertUnwindSafe<T> {}
|
||||
|
||||
// not covered via the Shared impl above b/c the inner contents use
|
||||
// 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> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Arc<T> {}
|
||||
|
||||
// Pretty simple implementations for the `RefUnwindSafe` marker trait,
|
||||
// basically just saying that `UnsafeCell` is the
|
||||
// only thing which doesn't implement it (which then transitively applies to
|
||||
// everything else).
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T: ?Sized> !RefUnwindSafe for UnsafeCell<T> {}
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> RefUnwindSafe for AssertUnwindSafe<T> {}
|
||||
|
||||
#[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
|
||||
impl<T: ?Sized> RefUnwindSafe for Mutex<T> {}
|
||||
#[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
|
||||
impl<T: ?Sized> RefUnwindSafe for RwLock<T> {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicIsize {}
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicI8 {}
|
||||
#[cfg(target_has_atomic_load_store = "16")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicI16 {}
|
||||
#[cfg(target_has_atomic_load_store = "32")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicI32 {}
|
||||
#[cfg(target_has_atomic_load_store = "64")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicI64 {}
|
||||
#[cfg(target_has_atomic_load_store = "128")]
|
||||
#[unstable(feature = "integer_atomics", issue = "32976")]
|
||||
impl RefUnwindSafe for atomic::AtomicI128 {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicUsize {}
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicU8 {}
|
||||
#[cfg(target_has_atomic_load_store = "16")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicU16 {}
|
||||
#[cfg(target_has_atomic_load_store = "32")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicU32 {}
|
||||
#[cfg(target_has_atomic_load_store = "64")]
|
||||
#[stable(feature = "integer_atomics_stable", since = "1.34.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicU64 {}
|
||||
#[cfg(target_has_atomic_load_store = "128")]
|
||||
#[unstable(feature = "integer_atomics", issue = "32976")]
|
||||
impl RefUnwindSafe for atomic::AtomicU128 {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "8")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl RefUnwindSafe for atomic::AtomicBool {}
|
||||
|
||||
#[cfg(target_has_atomic_load_store = "ptr")]
|
||||
#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")]
|
||||
impl<T> RefUnwindSafe for atomic::AtomicPtr<T> {}
|
||||
|
||||
// https://github.com/rust-lang/rust/issues/62301
|
||||
#[stable(feature = "hashbrown", since = "1.36.0")]
|
||||
impl<K, V, S> UnwindSafe for collections::HashMap<K, V, S>
|
||||
|
|
@ -323,61 +73,6 @@ where
|
|||
{
|
||||
}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> Deref for AssertUnwindSafe<T> {
|
||||
type Target = T;
|
||||
|
||||
fn deref(&self) -> &T {
|
||||
&self.0
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<T> DerefMut for AssertUnwindSafe<T> {
|
||||
fn deref_mut(&mut self) -> &mut T {
|
||||
&mut self.0
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "catch_unwind", since = "1.9.0")]
|
||||
impl<R, F: FnOnce() -> R> FnOnce<()> for AssertUnwindSafe<F> {
|
||||
type Output = R;
|
||||
|
||||
extern "rust-call" fn call_once(self, _args: ()) -> R {
|
||||
(self.0)()
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "std_debug", since = "1.16.0")]
|
||||
impl<T: fmt::Debug> fmt::Debug for AssertUnwindSafe<T> {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.debug_tuple("AssertUnwindSafe").field(&self.0).finish()
|
||||
}
|
||||
}
|
||||
|
||||
#[stable(feature = "futures_api", since = "1.36.0")]
|
||||
impl<F: Future> Future for AssertUnwindSafe<F> {
|
||||
type Output = F::Output;
|
||||
|
||||
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
|
||||
let pinned_field = unsafe { Pin::map_unchecked_mut(self, |x| &mut x.0) };
|
||||
F::poll(pinned_field, cx)
|
||||
}
|
||||
}
|
||||
|
||||
#[unstable(feature = "async_stream", issue = "79024")]
|
||||
impl<S: Stream> Stream for AssertUnwindSafe<S> {
|
||||
type Item = S::Item;
|
||||
|
||||
fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<S::Item>> {
|
||||
unsafe { self.map_unchecked_mut(|x| &mut x.0) }.poll_next(cx)
|
||||
}
|
||||
|
||||
fn size_hint(&self) -> (usize, Option<usize>) {
|
||||
self.0.size_hint()
|
||||
}
|
||||
}
|
||||
|
||||
/// Invokes a closure, capturing the cause of an unwinding panic if one occurs.
|
||||
///
|
||||
/// This function will return `Ok` with the closure's result if the closure
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue