Merge pull request #362 from japaric/panic

document #[panic_handler]

Author: ehuss

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)

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

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.
+
+<!-- NOTE(ignore) `mdbook test` doesn't support `no_std` code -->
+
+``` 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