From 55d9e0f601d9154d99a2fec3d803b42cbf60ff2a Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Thu, 18 Mar 2021 09:52:21 +0100 Subject: [PATCH 1/4] Include output stream in `panic!()` documentation --- library/core/src/macros/panic.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 6e502426df906..e5e286ca5a288 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -10,8 +10,8 @@ tests. `panic!` is closely tied with the `unwrap` method of both `panic!` when they are set to [`None`] or [`Err`] variants. This macro is used to inject panic into a Rust thread, causing the thread to -panic entirely. This macro panics with a string and uses the [`format!`] syntax -for building the message. +panic entirely. The string built by this macro (using the [`format!`] syntax +for building the actual message) is printed to `stderr`. Each thread's panic can be reaped as the [`Box`]`<`[`Any`]`>` type, which contains either a `&str` or `String` for regular `panic!()` invocations. From 61e5d549b49152b5fdc714fde93ab5c55e301127 Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Thu, 18 Mar 2021 14:23:05 +0100 Subject: [PATCH 2/4] Add more information about panicking This includes the description of the default `std` behavior and mentions the `panic::set_hook()` function. --- library/core/src/macros/panic.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index e5e286ca5a288..39fe9d8077ebc 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -9,11 +9,14 @@ tests. `panic!` is closely tied with the `unwrap` method of both [`Option`][ounwrap] and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set to [`None`] or [`Err`] variants. -This macro is used to inject panic into a Rust thread, causing the thread to -panic entirely. The string built by this macro (using the [`format!`] syntax -for building the actual message) is printed to `stderr`. - -Each thread's panic can be reaped as the [`Box`]`<`[`Any`]`>` type, +When using `panic!()` you can specify a string payload, that is built using +the [`format!`] syntax. That payload is used when injecting the panic into +the calling Rust thread, causing the thread to panic entirely. + +The default `std` panic handling strategy is to print the message payload to +the `stderr` along with the file/line/column information of the `panic!()` +call. You can override the panic hook using [`std::panic::set_hook()`]. +Inside the hook a panic can be reaped as the [`Box`]`<`[`Any`]`>` type, which contains either a `&str` or `String` for regular `panic!()` invocations. To panic with a value of another other type, [`panic_any`] can be used. @@ -26,6 +29,7 @@ See also the macro [`compile_error!`], for raising errors during compilation. [ounwrap]: Option::unwrap [runwrap]: Result::unwrap +[`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html [`panic_any`]: ../std/panic/fn.panic_any.html [`Box`]: ../std/boxed/struct.Box.html [`Any`]: crate::any::Any From d5e45b50cdfc029a061229d9edf5f5fa58eb0353 Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Thu, 18 Mar 2021 15:15:28 +0100 Subject: [PATCH 3/4] Incorporate review feedback #2 --- library/core/src/macros/panic.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index 39fe9d8077ebc..e59be12a6898c 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -13,10 +13,11 @@ When using `panic!()` you can specify a string payload, that is built using the [`format!`] syntax. That payload is used when injecting the panic into the calling Rust thread, causing the thread to panic entirely. -The default `std` panic handling strategy is to print the message payload to -the `stderr` along with the file/line/column information of the `panic!()` +The behavior of the default `std` hook, i.e. the code, that runs directy +after the panic is invoked, is to print the message payload to the +`stderr` along with the file/line/column information of the `panic!()` call. You can override the panic hook using [`std::panic::set_hook()`]. -Inside the hook a panic can be reaped as the [`Box`]`<`[`Any`]`>` type, +Inside the hook a panic can be accessed as a `&dyn Any + Send`, which which contains either a `&str` or `String` for regular `panic!()` invocations. To panic with a value of another other type, [`panic_any`] can be used. From 19bd0669b45fcc5ce81b8003cafccf318c3cc22e Mon Sep 17 00:00:00 2001 From: "J. Frimmel" <31166235+jfrimmel@users.noreply.github.com> Date: Thu, 18 Mar 2021 21:15:19 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Josh Triplett --- library/core/src/macros/panic.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md index e59be12a6898c..5127a16bbfd86 100644 --- a/library/core/src/macros/panic.md +++ b/library/core/src/macros/panic.md @@ -13,11 +13,11 @@ When using `panic!()` you can specify a string payload, that is built using the [`format!`] syntax. That payload is used when injecting the panic into the calling Rust thread, causing the thread to panic entirely. -The behavior of the default `std` hook, i.e. the code, that runs directy -after the panic is invoked, is to print the message payload to the +The behavior of the default `std` hook, i.e. the code that runs directly +after the panic is invoked, is to print the message payload to `stderr` along with the file/line/column information of the `panic!()` call. You can override the panic hook using [`std::panic::set_hook()`]. -Inside the hook a panic can be accessed as a `&dyn Any + Send`, which +Inside the hook a panic can be accessed as a `&dyn Any + Send`, which contains either a `&str` or `String` for regular `panic!()` invocations. To panic with a value of another other type, [`panic_any`] can be used.