diff --git a/core/src/error.md b/core/src/error.md index a5deb71e6b80a..8d5a623df4b75 100644 --- a/core/src/error.md +++ b/core/src/error.md @@ -17,7 +17,7 @@ The following are the primary interfaces of the panic system and the responsibilities they cover: * [`panic!`] and [`panic_any`] (Constructing, Propagated automatically) -* [`PanicInfo`] (Reporting) +* [`PanicHookInfo`] (Reporting) * [`set_hook`], [`take_hook`], and [`#[panic_handler]`][panic-handler] (Reporting) * [`catch_unwind`] and [`resume_unwind`] (Discarding, Propagating) @@ -125,7 +125,7 @@ expect-as-precondition style error messages remember to focus on the word should be available and executable by the current user". [`panic_any`]: ../../std/panic/fn.panic_any.html -[`PanicInfo`]: crate::panic::PanicInfo +[`PanicHookInfo`]: ../../std/panic/struct.PanicHookInfo.html [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html [`resume_unwind`]: ../../std/panic/fn.resume_unwind.html [`downcast`]: crate::error::Error diff --git a/core/src/panic/location.rs b/core/src/panic/location.rs index eb27da1724ec9..8c04994ac0fc4 100644 --- a/core/src/panic/location.rs +++ b/core/src/panic/location.rs @@ -2,9 +2,10 @@ use crate::fmt; /// A struct containing information about the location of a panic. /// -/// This structure is created by [`PanicInfo::location()`]. +/// This structure is created by [`PanicHookInfo::location()`] and [`PanicInfo::location()`]. /// /// [`PanicInfo::location()`]: crate::panic::PanicInfo::location +/// [`PanicHookInfo::location()`]: ../../std/panic/struct.PanicHookInfo.html#method.location /// /// # Examples /// diff --git a/core/src/panic/panic_info.rs b/core/src/panic/panic_info.rs index 2a0cd8fda61ba..7c792a58d2a8e 100644 --- a/core/src/panic/panic_info.rs +++ b/core/src/panic/panic_info.rs @@ -5,14 +5,9 @@ use crate::panic::Location; /// /// A `PanicInfo` structure is passed to the panic handler defined by `#[panic_handler]`. /// -/// There two `PanicInfo` types: -/// - `core::panic::PanicInfo`, which is used as an argument to a `#[panic_handler]` in `#![no_std]` programs. -/// - [`std::panic::PanicInfo`], which is used as an argument to a panic hook set by [`std::panic::set_hook`]. +/// For the type used by the panic hook mechanism in `std`, see [`std::panic::PanicHookInfo`]. /// -/// This is the first one. -/// -/// [`std::panic::set_hook`]: ../../std/panic/fn.set_hook.html -/// [`std::panic::PanicInfo`]: ../../std/panic/struct.PanicInfo.html +/// [`std::panic::PanicHookInfo`]: ../../std/panic/struct.PanicHookInfo.html #[lang = "panic_info"] #[stable(feature = "panic_hooks", since = "1.10.0")] #[derive(Debug)] @@ -78,13 +73,13 @@ impl<'a> PanicInfo<'a> { /// Returns the payload associated with the panic. /// /// On `core::panic::PanicInfo`, this method never returns anything useful. - /// It only exists because of compatibility with [`std::panic::PanicInfo`], + /// It only exists because of compatibility with [`std::panic::PanicHookInfo`], /// which used to be the same type. /// - /// See [`std::panic::PanicInfo::payload`]. + /// See [`std::panic::PanicHookInfo::payload`]. /// - /// [`std::panic::PanicInfo`]: ../../std/panic/struct.PanicInfo.html - /// [`std::panic::PanicInfo::payload`]: ../../std/panic/struct.PanicInfo.html#method.payload + /// [`std::panic::PanicHookInfo`]: ../../std/panic/struct.PanicHookInfo.html + /// [`std::panic::PanicHookInfo::payload`]: ../../std/panic/struct.PanicHookInfo.html#method.payload #[deprecated(since = "1.74.0", note = "this never returns anything useful")] #[stable(feature = "panic_hooks", since = "1.10.0")] #[allow(deprecated, deprecated_in_future)] diff --git a/core/src/panicking.rs b/core/src/panicking.rs index 94b4113b24518..97fb1d6b7323f 100644 --- a/core/src/panicking.rs +++ b/core/src/panicking.rs @@ -1,11 +1,11 @@ //! Panic support for core //! -//! In core, panicking is always done with a message, resulting in a core::panic::PanicInfo -//! containing a fmt::Arguments. In std, however, panicking can be done with panic_any, which throws -//! a `Box` containing any type of value. Because of this, std::panic::PanicInfo is a -//! different type, which contains a &dyn Any instead of a fmt::Arguments. -//! std's panic handler will convert the fmt::Arguments to a &dyn Any containing either a -//! &'static str or String containing the formatted message. +//! In core, panicking is always done with a message, resulting in a `core::panic::PanicInfo` +//! containing a `fmt::Arguments`. In std, however, panicking can be done with panic_any, which +//! throws a `Box` containing any type of value. Because of this, +//! `std::panic::PanicHookInfo` is a different type, which contains a `&dyn Any` instead of a +//! `fmt::Arguments`. std's panic handler will convert the `fmt::Arguments` to a `&dyn Any` +//! containing either a `&'static str` or `String` containing the formatted message. //! //! The core library cannot define any panic handler, but it can invoke it. //! This means that the functions inside of core are allowed to panic, but to be diff --git a/std/src/panic.rs b/std/src/panic.rs index ca0ec12a6009c..77defe14b708a 100644 --- a/std/src/panic.rs +++ b/std/src/panic.rs @@ -10,15 +10,21 @@ use crate::sync::atomic::{AtomicU8, Ordering}; use crate::sync::{Condvar, Mutex, RwLock}; use crate::thread::Result; +#[stable(feature = "panic_hooks", since = "1.10.0")] +#[deprecated( + since = "1.77.0", + note = "use `PanicHookInfo` instead", + suggestion = "std::panic::PanicHookInfo" +)] /// A struct providing information about a panic. /// -/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`] function. -/// -/// There two `PanicInfo` types: -/// - [`core::panic::PanicInfo`], which is used as an argument to a `#[panic_handler]` in `#![no_std]` programs. -/// - `std::panic::PanicInfo`, which is used as an argument to a panic hook set by [`set_hook`]. +/// `PanicInfo` has been renamed to [`PanicHookInfo`] to avoid confusion with +/// [`core::panic::PanicInfo`]. +pub type PanicInfo<'a> = PanicHookInfo<'a>; + +/// A struct providing information about a panic. /// -/// This is the second one. +/// `PanicHookInfo` structure is passed to a panic hook set by the [`set_hook`] function. /// /// # Examples /// @@ -32,18 +38,17 @@ use crate::thread::Result; /// panic!("critical system failure"); /// ``` /// -/// [`core::panic::PanicInfo`]: ../../core/panic/struct.PanicInfo.html /// [`set_hook`]: ../../std/panic/fn.set_hook.html -#[stable(feature = "panic_hooks", since = "1.10.0")] +#[stable(feature = "panic_hook_info", since = "CURRENT_RUSTC_VERSION")] #[derive(Debug)] -pub struct PanicInfo<'a> { +pub struct PanicHookInfo<'a> { payload: &'a (dyn Any + Send), location: &'a Location<'a>, can_unwind: bool, force_no_backtrace: bool, } -impl<'a> PanicInfo<'a> { +impl<'a> PanicHookInfo<'a> { #[inline] pub(crate) fn new( location: &'a Location<'a>, @@ -51,7 +56,7 @@ impl<'a> PanicInfo<'a> { can_unwind: bool, force_no_backtrace: bool, ) -> Self { - PanicInfo { payload, location, can_unwind, force_no_backtrace } + PanicHookInfo { payload, location, can_unwind, force_no_backtrace } } /// Returns the payload associated with the panic. @@ -145,7 +150,7 @@ impl<'a> PanicInfo<'a> { } #[stable(feature = "panic_hook_display", since = "1.26.0")] -impl fmt::Display for PanicInfo<'_> { +impl fmt::Display for PanicHookInfo<'_> { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { formatter.write_str("panicked at ")?; self.location.fmt(formatter)?; @@ -204,7 +209,7 @@ pub use core::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe}; /// The message can be of any (`Any + Send`) type, not just strings. /// /// The message is wrapped in a `Box<'static + Any + Send>`, which can be -/// accessed later using [`PanicInfo::payload`]. +/// accessed later using [`PanicHookInfo::payload`]. /// /// See the [`panic!`] macro for more information about panicking. #[stable(feature = "panic_any", since = "1.51.0")] diff --git a/std/src/panicking.rs b/std/src/panicking.rs index 15544de9ff81f..caab7ed4b81a6 100644 --- a/std/src/panicking.rs +++ b/std/src/panicking.rs @@ -9,7 +9,7 @@ #![deny(unsafe_op_in_unsafe_fn)] -use crate::panic::{BacktraceStyle, PanicInfo}; +use crate::panic::{BacktraceStyle, PanicHookInfo}; use core::panic::{Location, PanicPayload}; use crate::any::Any; @@ -70,12 +70,12 @@ extern "C" fn __rust_foreign_exception() -> ! { enum Hook { Default, - Custom(Box) + 'static + Sync + Send>), + Custom(Box) + 'static + Sync + Send>), } impl Hook { #[inline] - fn into_box(self) -> Box) + 'static + Sync + Send> { + fn into_box(self) -> Box) + 'static + Sync + Send> { match self { Hook::Default => Box::new(default_hook), Hook::Custom(hook) => hook, @@ -105,7 +105,7 @@ static HOOK: RwLock = RwLock::new(Hook::Default); /// /// [`take_hook`]: ./fn.take_hook.html /// -/// The hook is provided with a `PanicInfo` struct which contains information +/// The hook is provided with a `PanicHookInfo` struct which contains information /// about the origin of the panic, including the payload passed to `panic!` and /// the source code location from which the panic originated. /// @@ -129,7 +129,7 @@ static HOOK: RwLock = RwLock::new(Hook::Default); /// panic!("Normal panic"); /// ``` #[stable(feature = "panic_hooks", since = "1.10.0")] -pub fn set_hook(hook: Box) + 'static + Sync + Send>) { +pub fn set_hook(hook: Box) + 'static + Sync + Send>) { if thread::panicking() { panic!("cannot modify the panic hook from a panicking thread"); } @@ -173,7 +173,7 @@ pub fn set_hook(hook: Box) + 'static + Sync + Send>) { /// ``` #[must_use] #[stable(feature = "panic_hooks", since = "1.10.0")] -pub fn take_hook() -> Box) + 'static + Sync + Send> { +pub fn take_hook() -> Box) + 'static + Sync + Send> { if thread::panicking() { panic!("cannot modify the panic hook from a panicking thread"); } @@ -219,7 +219,7 @@ pub fn take_hook() -> Box) + 'static + Sync + Send> { #[unstable(feature = "panic_update_hook", issue = "92649")] pub fn update_hook(hook_fn: F) where - F: Fn(&(dyn Fn(&PanicInfo<'_>) + Send + Sync + 'static), &PanicInfo<'_>) + F: Fn(&(dyn Fn(&PanicHookInfo<'_>) + Send + Sync + 'static), &PanicHookInfo<'_>) + Sync + Send + 'static, @@ -234,7 +234,7 @@ where } /// The default panic handler. -fn default_hook(info: &PanicInfo<'_>) { +fn default_hook(info: &PanicHookInfo<'_>) { // If this is a double panic, make sure that we print a backtrace // for this panic. Otherwise only print it if logging is enabled. let backtrace = if info.force_no_backtrace() { @@ -791,10 +791,15 @@ fn rust_panic_with_hook( // formatting.) Hook::Default if panic_output().is_none() => {} Hook::Default => { - default_hook(&PanicInfo::new(location, payload.get(), can_unwind, force_no_backtrace)); + default_hook(&PanicHookInfo::new( + location, + payload.get(), + can_unwind, + force_no_backtrace, + )); } Hook::Custom(ref hook) => { - hook(&PanicInfo::new(location, payload.get(), can_unwind, force_no_backtrace)); + hook(&PanicHookInfo::new(location, payload.get(), can_unwind, force_no_backtrace)); } } diff --git a/test/src/lib.rs b/test/src/lib.rs index 7bd08a0605f83..7aff7fe1fdd68 100644 --- a/test/src/lib.rs +++ b/test/src/lib.rs @@ -58,7 +58,7 @@ use std::{ env, io, io::prelude::Write, mem::ManuallyDrop, - panic::{self, catch_unwind, AssertUnwindSafe, PanicInfo}, + panic::{self, catch_unwind, AssertUnwindSafe, PanicHookInfo}, process::{self, Command, Termination}, sync::mpsc::{channel, Sender}, sync::{Arc, Mutex}, @@ -123,7 +123,7 @@ pub fn test_main(args: &[String], tests: Vec, options: Option| { + move |info: &'_ PanicHookInfo<'_>| { if !info.can_unwind() { std::mem::forget(std::io::stderr().lock()); let mut stdout = ManuallyDrop::new(std::io::stdout().lock()); @@ -726,7 +726,7 @@ fn spawn_test_subprocess( fn run_test_in_spawned_subprocess(desc: TestDesc, runnable_test: RunnableTest) -> ! { let builtin_panic_hook = panic::take_hook(); - let record_result = Arc::new(move |panic_info: Option<&'_ PanicInfo<'_>>| { + let record_result = Arc::new(move |panic_info: Option<&'_ PanicHookInfo<'_>>| { let test_result = match panic_info { Some(info) => calc_result(&desc, Err(info.payload()), &None, &None), None => calc_result(&desc, Ok(()), &None, &None),