1\#\[no\_panic\]
2===============
3
4[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/no--panic-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/no-panic)
5[<img alt="crates.io" src="https://img.shields.io/crates/v/no-panic.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/no-panic)
6[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-no--panic-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/no-panic)
7[<img alt="build status" src="https://img.shields.io/github/workflow/status/dtolnay/no-panic/CI/master?style=for-the-badge" height="20">](https://github.com/dtolnay/no-panic/actions?query=branch%3Amaster)
8
9A Rust attribute macro to require that the compiler prove a function can't ever
10panic.
11
12```toml
13[dependencies]
14no-panic = "0.1"
15```
16
17```rust
18use no_panic::no_panic;
19
20#[no_panic]
21fn demo(s: &str) -> &str {
22    &s[1..]
23}
24
25fn main() {
26    println!("{}", demo("input string"));
27}
28```
29
30If the function does panic (or the compiler fails to prove that the function
31cannot panic), the program fails to compile with a linker error that identifies
32the function name. Let's trigger that by passing a string that cannot be sliced
33at the first byte:
34
35```rust
36fn main() {
37    println!("{}", demo("\u{1f980}input string"));
38}
39```
40
41```console
42   Compiling no-panic-demo v0.0.1
43error: linking with `cc` failed: exit code: 1
44  |
45  = note: /no-panic-demo/target/release/deps/no_panic_demo-7170785b672ae322.no_p
46anic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs.rcgu.o: In function `_$LT$no_pani
47c_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$::drop::h72f8f423002
48b8d9f':
49          no_panic_demo1-cba7f4b666ccdbcbbf02b7348e5df1b2.rs:(.text._ZN72_$LT$no
50_panic_demo..demo..__NoPanic$u20$as$u20$core..ops..drop..Drop$GT$4drop17h72f8f42
513002b8d9fE+0x2): undefined reference to `
52
53          ERROR[no-panic]: detected panic in function `demo`
54          '
55          collect2: error: ld returned 1 exit status
56```
57
58The error is not stellar but notice the ERROR\[no-panic\] part at the end that
59provides the name of the offending function.
60
61*Compiler support: requires rustc 1.31+*
62
63<br>
64
65### Caveats
66
67- Functions that require some amount of optimization to prove that they do not
68  panic may no longer compile in debug mode after being marked `#[no_panic]`.
69
70- Panic detection happens at link time across the entire dependency graph, so
71  any Cargo commands that do not invoke a linker will not trigger panic
72  detection. This includes `cargo build` of library crates and `cargo check` of
73  binary and library crates.
74
75- The attribute is useless in code built with `panic = "abort"`.
76
77If you find that code requires optimization to pass `#[no_panic]`, either make
78no-panic an optional dependency that you only enable in release builds, or add a
79section like the following to Cargo.toml to enable very basic optimization in
80debug builds.
81
82```toml
83[profile.dev]
84opt-level = 1
85```
86
87If the code that you need to prove isn't panicking makes function calls to
88non-generic non-inline functions from a different crate, you may need thin LTO
89enabled for the linker to deduce those do not panic.
90
91```toml
92[profile.release]
93lto = "thin"
94```
95
96If you want no\_panic to just assume that some function you call doesn't panic,
97and get Undefined Behavior if it does at runtime, see [dtolnay/no-panic#16]; try
98wrapping that call in an `unsafe extern "C"` wrapper.
99
100[dtolnay/no-panic#16]: https://github.com/dtolnay/no-panic/issues/16
101
102<br>
103
104### Acknowledgments
105
106The linker error technique is based on [Kixunil]'s crate [`dont_panic`]. Check
107out that crate for other convenient ways to require absence of panics.
108
109[Kixunil]: https://github.com/Kixunil
110[`dont_panic`]: https://github.com/Kixunil/dont_panic
111
112<br>
113
114#### License
115
116<sup>
117Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
1182.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
119</sup>
120
121<br>
122
123<sub>
124Unless you explicitly state otherwise, any contribution intentionally submitted
125for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
126be dual licensed as above, without any additional terms or conditions.
127</sub>
128