diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3cbae0714..3a2a46ec0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -113,6 +113,8 @@ - [Application Binary Interface](abi.md) +- [The Rust runtime](runtime.md) + [Appendix: Influences](influences.md) [Appendix: As-yet-undocumented Features](undocumented.md) 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 new file mode 100644 index 000000000..09fd888bf --- /dev/null +++ b/src/runtime.md @@ -0,0 +1,57 @@ +# The Rust runtime + +This section documents features that define some aspects of the Rust runtime. + +## The `panic_handler` attribute + +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. + +Below is shown a `panic_handler` function that logs the panic message and then halts the +thread. + + + +``` rust, ignore +#![no_std] + +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 = Sink::new(); + + // 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` 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. + +[`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