From 1242944935d1ad63eafc363738b2c767ef2b3205 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 20 Jun 2018 14:08:18 -0500 Subject: [PATCH 1/6] document #[panic_implementation] --- src/SUMMARY.md | 2 ++ src/beneath-std.md | 10 ++++++++++ src/panic-implementation.md | 35 +++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 src/beneath-std.md create mode 100644 src/panic-implementation.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3cbae0714..7983a13db 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -112,6 +112,8 @@ - [Constant Evaluation](const_eval.md) - [Application Binary Interface](abi.md) +- [Beneath `std`](beneath-std.md) + - [#[panic_implementation]](panic-implementation.md) [Appendix: Influences](influences.md) diff --git a/src/beneath-std.md b/src/beneath-std.md new file mode 100644 index 000000000..17ab48959 --- /dev/null +++ b/src/beneath-std.md @@ -0,0 +1,10 @@ +# Beneath `std` + +This section documents (or will document) features that are provided by the standard library and +that `#![no_std]` developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A +(likely incomplete) list of such features is shown below: + +- #[lang = "eh_personality"] +- #[lang = "start"] +- #[lang = "termination"] +- #[panic_implementation] diff --git a/src/panic-implementation.md b/src/panic-implementation.md new file mode 100644 index 000000000..3fe8735c3 --- /dev/null +++ b/src/panic-implementation.md @@ -0,0 +1,35 @@ +## #[panic_implementation] + +The `#[panic_implementation]` attribute can only be applied to a function with signature +`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of `panic!` in +`#![no_std]` applications. There must be a *single* `#[panic_implementation]` function in the +dependency graph of a binary / dylib / cdylib crate. + +The `PanicInfo` struct contains information about the location of the panic. The API of `PanicInfo` +can be found in the [API docs]. As of 1.28-beta (2018-06-21) there's a difference between +`core::panic!` and `std::panic!`: the former doesn't accept non-string payloads -- that is +`core::panic!(42)` is not accepted. In the future `core::panic!` may gain support for non-string +payloads. The implementation of `core::panic!` can be found in `src/libcore/{macros,panicking}.rs` + +[API docs]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html + +Below is shown a `#[panic_implementation]` that logs the panic message and then aborts the program. + +``` rust +#![feature(core_intrinsics)] +#![feature(panic_implementation)] +#![no_std] + +use core::intrinsics; +use core::panic::PanicInfo; + +#[panic_implementation] +fn panic(info: &PanicInfo) -> ! { + let mut sink = /* .. */; + + // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` + let _ = writeln!(sink, "{}", info); + + unsafe { intrinsics::abort() } +} +``` From dba3cbb0d6c5b8bad5733c367b153cfca691eced Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Thu, 21 Jun 2018 21:58:03 -0500 Subject: [PATCH 2/6] address review comments --- src/SUMMARY.md | 1 - src/beneath-std.md | 45 ++++++++++++++++++++++++++++++------- src/panic-implementation.md | 35 ----------------------------- 3 files changed, 37 insertions(+), 44 deletions(-) delete mode 100644 src/panic-implementation.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7983a13db..b7bba853f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -113,7 +113,6 @@ - [Application Binary Interface](abi.md) - [Beneath `std`](beneath-std.md) - - [#[panic_implementation]](panic-implementation.md) [Appendix: Influences](influences.md) diff --git a/src/beneath-std.md b/src/beneath-std.md index 17ab48959..16f159ec8 100644 --- a/src/beneath-std.md +++ b/src/beneath-std.md @@ -1,10 +1,39 @@ # Beneath `std` -This section documents (or will document) features that are provided by the standard library and -that `#![no_std]` developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A -(likely incomplete) list of such features is shown below: - -- #[lang = "eh_personality"] -- #[lang = "start"] -- #[lang = "termination"] -- #[panic_implementation] +This section documents features that are provided by the standard library and that `#![no_std]` +developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A list of such +features is shown below: + +- `#[panic_implementation]` + +## `#[panic_implementation]` + +The `panic_implementation` attribute can only be applied to a function with signature +`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of `panic!` in +`#![no_std]` applications. The [`PanicInfo`] struct contains information about the location of the +panic. There must be a single `panic_implementation` function in the dependency graph of a +binary, dylib or cdylib crate. + +[`PanicInfo`]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html + +Below is shown a `panic_implementation` function that logs the panic message and then aborts the +program. + +``` rust +#![feature(core_intrinsics)] +#![feature(panic_implementation)] +#![no_std] + +use core::intrinsics; +use core::panic::PanicInfo; + +#[panic_implementation] +fn panic(info: &PanicInfo) -> ! { + let mut sink = /* .. */; + + // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` + let _ = writeln!(sink, "{}", info); + + unsafe { intrinsics::abort() } +} +``` diff --git a/src/panic-implementation.md b/src/panic-implementation.md deleted file mode 100644 index 3fe8735c3..000000000 --- a/src/panic-implementation.md +++ /dev/null @@ -1,35 +0,0 @@ -## #[panic_implementation] - -The `#[panic_implementation]` attribute can only be applied to a function with signature -`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of `panic!` in -`#![no_std]` applications. There must be a *single* `#[panic_implementation]` function in the -dependency graph of a binary / dylib / cdylib crate. - -The `PanicInfo` struct contains information about the location of the panic. The API of `PanicInfo` -can be found in the [API docs]. As of 1.28-beta (2018-06-21) there's a difference between -`core::panic!` and `std::panic!`: the former doesn't accept non-string payloads -- that is -`core::panic!(42)` is not accepted. In the future `core::panic!` may gain support for non-string -payloads. The implementation of `core::panic!` can be found in `src/libcore/{macros,panicking}.rs` - -[API docs]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html - -Below is shown a `#[panic_implementation]` that logs the panic message and then aborts the program. - -``` rust -#![feature(core_intrinsics)] -#![feature(panic_implementation)] -#![no_std] - -use core::intrinsics; -use core::panic::PanicInfo; - -#[panic_implementation] -fn panic(info: &PanicInfo) -> ! { - let mut sink = /* .. */; - - // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` - let _ = writeln!(sink, "{}", info); - - unsafe { intrinsics::abort() } -} -``` From ddac383b98f46af4984afca396c6294fa9ef1840 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Fri, 7 Sep 2018 12:35:38 +0200 Subject: [PATCH 3/6] panic_implementation -> panic_handler; beneath std -> the Rust runtime --- src/SUMMARY.md | 3 ++- src/beneath-std.md | 39 --------------------------------------- src/runtime.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 40 deletions(-) delete mode 100644 src/beneath-std.md create mode 100644 src/runtime.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b7bba853f..3a2a46ec0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -112,7 +112,8 @@ - [Constant Evaluation](const_eval.md) - [Application Binary Interface](abi.md) -- [Beneath `std`](beneath-std.md) + +- [The Rust runtime](runtime.md) [Appendix: Influences](influences.md) diff --git a/src/beneath-std.md b/src/beneath-std.md deleted file mode 100644 index 16f159ec8..000000000 --- a/src/beneath-std.md +++ /dev/null @@ -1,39 +0,0 @@ -# Beneath `std` - -This section documents features that are provided by the standard library and that `#![no_std]` -developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A list of such -features is shown below: - -- `#[panic_implementation]` - -## `#[panic_implementation]` - -The `panic_implementation` attribute can only be applied to a function with signature -`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of `panic!` in -`#![no_std]` applications. The [`PanicInfo`] struct contains information about the location of the -panic. There must be a single `panic_implementation` function in the dependency graph of a -binary, dylib or cdylib crate. - -[`PanicInfo`]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html - -Below is shown a `panic_implementation` function that logs the panic message and then aborts the -program. - -``` rust -#![feature(core_intrinsics)] -#![feature(panic_implementation)] -#![no_std] - -use core::intrinsics; -use core::panic::PanicInfo; - -#[panic_implementation] -fn panic(info: &PanicInfo) -> ! { - let mut sink = /* .. */; - - // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` - let _ = writeln!(sink, "{}", info); - - unsafe { intrinsics::abort() } -} -``` diff --git a/src/runtime.md b/src/runtime.md new file mode 100644 index 000000000..44077886a --- /dev/null +++ b/src/runtime.md @@ -0,0 +1,43 @@ +# The Rust runtime + +This section documents features that define some aspects of the Rust runtime. A list of such +features is shown below: + +- `#[panic_handler]`, the panicking behavior + +## `#[panic_handler]` + +The `panic_handler` attribute can only be applied to a function with signature +`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of panics. The +[`PanicInfo`] struct contains information about the location of the panic. There must be a single +`panic_handler` function in the dependency graph of a binary, dylib or cdylib crate. + +[`PanicInfo`]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html + +Below is shown a `panic_handler` function that logs the panic message and then halts the +thread. + +``` rust +#![no_std] + +use core::intrinsics; +use core::panic::PanicInfo; + +#[panic_handler] +fn panic(info: &PanicInfo) -> ! { + let mut sink = /* .. */; + + // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` + let _ = writeln!(sink, "{}", info); + + loop {} +} +``` + +### Standard behavior + +The standard library provides an implementation of `panic_handler` than can be +statically customized using the `-C panic` flag. `-C panic=abort` makes panics +abort the process, and `-C panic=unwind` makes panics unwind the panicking +thread. If no panicking behavior is specified using `-C panic` one of these two +behaviors is chosen according to the compilation target. From 24f3bd83d3e4c7a8b1f9a273b1a43d6ccbdd4f3c Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Fri, 7 Sep 2018 20:49:30 +0200 Subject: [PATCH 4/6] ignore test --- src/runtime.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/src/runtime.md b/src/runtime.md index 44077886a..9da540964 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -17,15 +17,30 @@ The `panic_handler` attribute can only be applied to a function with signature Below is shown a `panic_handler` function that logs the panic message and then halts the thread. -``` rust + + +``` rust, ignore #![no_std] -use core::intrinsics; +use core::fmt::{self, Write}; use core::panic::PanicInfo; +struct Sink { + // .. +# _0: (), +} +# +# impl Sink { +# fn new() -> Sink { Sink { _0: () }} +# } +# +# impl fmt::Write for Sink { +# fn write_str(&mut self, _: &str) -> fmt::Result { Ok(()) } +# } + #[panic_handler] fn panic(info: &PanicInfo) -> ! { - let mut sink = /* .. */; + let mut sink = Sink::new(); // logs "panicked at '$reason', src/main.rs:27:4" to some `sink` let _ = writeln!(sink, "{}", info); From 1985db0770be33208843dd83cccd2fee2d386c74 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Fri, 7 Sep 2018 20:52:48 +0200 Subject: [PATCH 5/6] link to the book --- src/runtime.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/runtime.md b/src/runtime.md index 9da540964..616a760cb 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -51,8 +51,7 @@ fn panic(info: &PanicInfo) -> ! { ### Standard behavior -The standard library provides an implementation of `panic_handler` than can be -statically customized using the `-C panic` flag. `-C panic=abort` makes panics -abort the process, and `-C panic=unwind` makes panics unwind the panicking -thread. If no panicking behavior is specified using `-C panic` one of these two -behaviors is chosen according to the compilation target. +The standard library provides an implementation of `panic_handler` than defaults +to unwinding the stack but that can be [changed to abort the process][abort]. + +[abort]: ../book/2018-edition/ch09-01-unrecoverable-errors-with-panic.html From d17ef56220a497bca837cf5b4c94f9b824603b53 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 10 Mar 2019 19:32:13 -0700 Subject: [PATCH 6/6] Update panic_handler. - Address review comments. - Some minor formatting adjustments. --- src/attributes.md | 2 ++ src/runtime.md | 24 ++++++++++++------------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index caaffacd3..8117ad847 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -206,6 +206,7 @@ which can be used to control type layout. symbol for this item to its identifier. - [`used`] - on statics, this forces the compiler to keep the variable in the output object file. +- [`panic_handler`] — sets the function to handle panics. ### Deprecation @@ -632,3 +633,4 @@ pub fn f() {} [Expression Attributes]: expressions.html#expression-attributes [`meta` macro fragment specifier]: macros-by-example.html [`used`]: abi.html#the-used-attribute +[`panic_handler`]: runtime.html#the-panic_handler-attribute diff --git a/src/runtime.md b/src/runtime.md index 616a760cb..09fd888bf 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -1,19 +1,14 @@ # The Rust runtime -This section documents features that define some aspects of the Rust runtime. A list of such -features is shown below: +This section documents features that define some aspects of the Rust runtime. -- `#[panic_handler]`, the panicking behavior +## The `panic_handler` attribute -## `#[panic_handler]` - -The `panic_handler` attribute can only be applied to a function with signature -`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of panics. The +The *`panic_handler` attribute* can only be applied to a function with signature +`fn(&PanicInfo) -> !`. The function marked with this [attribute] defines the behavior of panics. The [`PanicInfo`] struct contains information about the location of the panic. There must be a single `panic_handler` function in the dependency graph of a binary, dylib or cdylib crate. -[`PanicInfo`]: https://doc.rust-lang.org/nightly/core/panic/struct.PanicInfo.html - Below is shown a `panic_handler` function that logs the panic message and then halts the thread. @@ -51,7 +46,12 @@ fn panic(info: &PanicInfo) -> ! { ### Standard behavior -The standard library provides an implementation of `panic_handler` than defaults -to unwinding the stack but that can be [changed to abort the process][abort]. +The standard library provides an implementation of `panic_handler` that +defaults to unwinding the stack but that can be [changed to abort the +process][abort]. The standard library's panic behavior can be modified at +runtime with the [set_hook] function. -[abort]: ../book/2018-edition/ch09-01-unrecoverable-errors-with-panic.html +[`PanicInfo`]: ../core/panic/struct.PanicInfo.html +[abort]: ../book/ch09-01-unrecoverable-errors-with-panic.html +[attribute]: attributes.html +[set_hook]: ../std/panic/fn.set_hook.html