Text of rust.docs.kernel.org › src › core › panicking.rs.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

panicking.rs - source

Skip to main content core/ panicking.rs 1 //! Panic support for core 2 //! 3 //! In core, panicking is always done with a message, resulting in a `core::panic::PanicInfo` 4 //! containing a `fmt::Arguments`. In std, however, panicking can be done with panic_any, which 5 //! throws a `Box<dyn Any>` containing any type of value. Because of this, 6 //! `std::panic::PanicHookInfo` is a different type, which contains a `&dyn Any` instead of a 7 //! `fmt::Arguments`. std's panic handler will convert the `fmt::Arguments` to a `&dyn Any` 8 //! containing either a `&'static str` or `String` containing the formatted message.

9 //! 10 //! The core library cannot define any panic handler, but it can invoke it. 11 //! This means that the functions inside of core are allowed to panic, but to be 12 //! useful an upstream crate must define panicking for core to use. The current 13 //! interface for panicking is: 14 //! 15 //! ``` 16 //! fn panic_impl(pi: &core::panic::PanicInfo<'_>) -> ! 17 //! # { loop {} } 18 //! ``` 19 //! 20 //! This module contains a few other panicking functions, but these are just the 21 //! necessary lang items for the compiler.

All panics are funneled through this 22 //! one function. The actual symbol is declared through the `#[panic_handler]` attribute. 23 24 #![allow(dead_code, missing_docs)] 25 #![unstable( 26 feature = "panic_internals" , 27 reason = "internal details of the implementation of the `panic!` and related macros" , 28 issue = "none" 29 )] 30 31 use crate ::fmt ; 32 use crate ::intrinsics::const_eval_select ; 33 use crate ::panic::{ Location , PanicInfo }; 34 35 #[cfg(feature = "panic_immediate_abort" )] 36 compile_error! ( 37 "panic_immediate_abort is now a real panic strategy! \ 38 Enable it with `panic = \"immediate-abort\"` in Cargo.toml, \ 39 or with the compiler flags `-Zunstable-options -Cpanic=immediate-abort`. \ 40 In both cases, you still need to build core, e.g. with `-Zbuild-std`" 41 ); 42 43 // First we define the two main entry points that all panics go through.

44 // In the end both are just convenience wrappers around `panic_impl`. 45 46 /// The entry point for panicking with a formatted message. 47 /// 48 /// This is designed to reduce the amount of code required at the call 49 /// site as much as possible (so that `panic!()` has as low an impact 50 /// on (e.g.) the inlining of other functions as possible), by moving 51 /// the actual formatting into this shared place. 52 // If panic=immediate-abort, inline the abort call, 53 // otherwise avoid inlining because of it is cold path.

54 #[cfg_attr(not(panic = "immediate-abort" ), inline(never), cold)] 55 #[cfg_attr(panic = "immediate-abort" , inline)] 56 #[track_caller] 57 #[lang = "panic_fmt" ] // needed for const-evaluated panics 58 #[rustc_do_not_const_check] // hooked by const-eval 59 #[rustc_const_stable_indirect] // must follow stable const rules since it is exposed to stable 60 pub const fn panic_fmt (fmt: fmt:: Arguments < '_ >) -> ! { 61 if cfg! (panic = "immediate-abort" ) { 62 super ::intrinsics:: abort () 63 } 64 65 // NOTE This function never crosses the FFI boundary; it's a Rust-to-Rust call 66 // that gets resolved to the `#[panic_handler]` function.

67 unsafe extern "Rust" { 68 #[lang = "panic_impl" ] 69 fn panic_impl(pi: & PanicInfo < '_ >) -> !; 70 } 71 72 let pi = PanicInfo :: new ( 73 & fmt , 74 Location :: caller (), 75 /* can_unwind */ true , 76 /* force_no_backtrace */ false , 77 ); 78 79 // SAFETY: `panic_impl` is defined in safe Rust code and thus is safe to call. 80 unsafe { panic_impl ( & pi ) } 81 } 82 83 /// Like `panic_fmt`, but for non-unwinding panics.

84 /// 85 /// Has to be a separate function so that it can carry the `rustc_nounwind` attribute. 86 #[cfg_attr(not(panic = "immediate-abort" ), inline(never), cold)] 87 #[cfg_attr(panic = "immediate-abort" , inline)] 88 #[track_caller] 89 // This attribute has the key side-effect that if the panic handler ignores `can_unwind` 90 // and unwinds anyway, we will hit the "unwinding out of nounwind function" guard, 91 // which causes a "panic in a function that cannot unwind".

92 #[rustc_nounwind] 93 #[rustc_const_stable_indirect] // must follow stable const rules since it is exposed to stable 94 #[rustc_allow_const_fn_unstable(const_eval_select)] 95 pub const fn panic_nounwind_fmt (fmt: fmt:: Arguments < '_ >, force_no_backtrace: bool ) -> ! { 96 const_eval_select! ( 97 @capture { fmt: fmt::Arguments< '_ >, force_no_backtrace: bool } -> !: 98 if const #[track_caller] { 99 // We don't unwind anyway at compile-time so we can call the regular `panic_fmt`.

100 panic_fmt(fmt) 101 } else #[track_caller] { 102 if cfg! (panic = "immediate-abort" ) { 103 super ::intrinsics::abort() 104 } 105 106 // NOTE This function never crosses the FFI boundary; it's a Rust-to-Rust call 107 // that gets resolved to the `#[panic_handler]` function. 108 unsafe extern "Rust" { 109 #[lang = "panic_impl" ] 110 fn panic_impl(pi: & PanicInfo< '_ >) -> !; 111 } 112 113 // PanicInfo with the `can_unwind` flag set to false forces an abort.

114 let pi = PanicInfo::new( 115 & fmt, 116 Location::caller(), 117 /* can_unwind */ false , 118 force_no_backtrace, 119 ); 120 121 // SAFETY: `panic_impl` is defined in safe Rust code and thus is safe to call. 122 unsafe { panic_impl( & pi) } 123 } 124 ) 125 } 126 127 // Next we define a bunch of higher-level wrappers that all bottom out in the two core functions 128 // above. 129 130 /// The underlying implementation of core's `panic!` macro when no formatting is used.

131 // Never inline unless panic=immediate-abort to avoid code 132 // bloat at the call sites as much as possible. 133 #[cfg_attr(not(panic = "immediate-abort" ), inline(never), cold)] 134 #[cfg_attr(panic = "immediate-abort" , inline)] 135 #[track_caller] 136 #[rustc_const_stable_indirect] // must follow stable const rules since it is exposed to stable 137 #[lang = "panic" ] // used by lints and miri for panics 138 pub const fn panic (expr: & 'static str ) -> ! { 139 // Use Arguments::from_str instead of format_args!("{expr}") to potentially 140 // reduce size overhead.

The format_args! macro uses str's Display trait to 141 // write expr, which calls Formatter::pad, which must accommodate string 142 // truncation and padding (even though none is used here). Using 143 // Arguments::from_str may allow the compiler to omit Formatter::pad from the 144 // output binary, saving up to a few kilobytes. 145 // However, this optimization only works for `'static` strings: `from_str` also makes this 146 // message return `Some` from `Arguments::as_str`, which means it can become part of the panic 147 // payload without any allocation or copying.

Shorter-lived strings would become invalid as 148 // stack frames get popped during unwinding, and couldn't be directly referenced from the 149 // payload. 150 panic_fmt (fmt:: Arguments :: from_str ( expr )); 151 } 152 153 // We generate functions for usage by compiler-generated assertions. 154 // 155 // Placing these functions in libcore means that all Rust programs can generate a jump into this 156 // code rather than expanding to panic("...") above, which adds extra bloat to call sites (for the 157 // constant string argument's pointer and length).

158 // 159 // This is especially important when this code is called often (e.g., with -Coverflow-checks) for 160 // reducing binary size impact. 161 macro_rules! panic_const { 162 ($( $lang :ident = $message :expr,)+) => { 163 $( 164 /// This is a panic called with a message that's a result of a MIR-produced Assert. 165 // 166 // never inline unless panic=immediate-abort to avoid code 167 // bloat at the call sites as much as possible 168 #[cfg_attr(not(panic = "immediate-abort" ), inline(never), cold)] 169 #[cfg_attr(panic = "immediate-abort" , inline)] 170 #[track_caller] 171 #[rustc_const_stable_indirect] // must follow stable const rules since it is exposed to stable 172 #[lang = stringify! ( $lang )] 173 pub const fn $lang () ->

The rest of this page is on the live site.