library/std/src/panic.rs

   1 //! Panic support in the standard library.
   2
   3 #![stable(feature = "std_panic", since = "1.9.0")]
   4
   5 use crate::any::Any;
   6 use crate::collections;
   7 use crate::panicking;
   8 use crate::sync::atomic::{AtomicUsize, Ordering};
   9 use crate::sync::{Mutex, RwLock};
  10 use crate::thread::Result;
  11
  12 #[doc(hidden)]
  13 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
  14 #[allow_internal_unstable(libstd_sys_internals, const_format_args, core_panic, rt)]
  15 #[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_2015_macro")]
  16 #[rustc_macro_transparency = "semitransparent"]
  17 pub macro panic_2015 {
  18     () => ({
  19         $crate::rt::begin_panic("explicit panic")
  20     }),
  21     ($msg:expr $(,)?) => ({
  22         $crate::rt::begin_panic($msg)
  23     }),
  24     // Special-case the single-argument case for const_panic.
  25     ("{}", $arg:expr $(,)?) => ({
  26         $crate::rt::panic_display(&$arg)
  27     }),
  28     ($fmt:expr, $($arg:tt)+) => ({
  29         $crate::rt::panic_fmt($crate::const_format_args!($fmt, $($arg)+))
  30     }),
  31 }
  32
  33 #[doc(hidden)]
  34 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
  35 pub use core::panic::panic_2021;
  36
  37 #[stable(feature = "panic_hooks", since = "1.10.0")]
  38 pub use crate::panicking::{set_hook, take_hook};
  39
  40 #[unstable(feature = "panic_update_hook", issue = "92649")]
  41 pub use crate::panicking::update_hook;
  42
  43 #[stable(feature = "panic_hooks", since = "1.10.0")]
  44 pub use core::panic::{Location, PanicInfo};
  45
  46 #[stable(feature = "catch_unwind", since = "1.9.0")]
  47 pub use core::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe};
  48
  49 /// Panic the current thread with the given message as the panic payload.
  50 ///
  51 /// The message can be of any (`Any + Send`) type, not just strings.
  52 ///
  53 /// The message is wrapped in a `Box<'static + Any + Send>`, which can be
  54 /// accessed later using [`PanicInfo::payload`].
  55 ///
  56 /// See the [`panic!`] macro for more information about panicking.
  57 #[stable(feature = "panic_any", since = "1.51.0")]
  58 #[inline]
  59 #[track_caller]
  60 pub fn panic_any<M: 'static + Any + Send>(msg: M) -> ! {
  61     crate::panicking::begin_panic(msg);
  62 }
  63
  64 #[stable(feature = "catch_unwind", since = "1.9.0")]
  65 impl<T: ?Sized> UnwindSafe for Mutex<T> {}
  66 #[stable(feature = "catch_unwind", since = "1.9.0")]
  67 impl<T: ?Sized> UnwindSafe for RwLock<T> {}
  68
  69 #[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
  70 impl<T: ?Sized> RefUnwindSafe for Mutex<T> {}
  71 #[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
  72 impl<T: ?Sized> RefUnwindSafe for RwLock<T> {}
  73
  74 // https://github.com/rust-lang/rust/issues/62301
  75 #[stable(feature = "hashbrown", since = "1.36.0")]
  76 impl<K, V, S> UnwindSafe for collections::HashMap<K, V, S>
  77 where
  78     K: UnwindSafe,
  79     V: UnwindSafe,
  80     S: UnwindSafe,
  81 {
  82 }
  83
  84 /// Invokes a closure, capturing the cause of an unwinding panic if one occurs.
  85 ///
  86 /// This function will return `Ok` with the closure's result if the closure
  87 /// does not panic, and will return `Err(cause)` if the closure panics. The
  88 /// `cause` returned is the object with which panic was originally invoked.
  89 ///
  90 /// It is currently undefined behavior to unwind from Rust code into foreign
  91 /// code, so this function is particularly useful when Rust is called from
  92 /// another language (normally C). This can run arbitrary Rust code, capturing a
  93 /// panic and allowing a graceful handling of the error.
  94 ///
  95 /// It is **not** recommended to use this function for a general try/catch
  96 /// mechanism. The [`Result`] type is more appropriate to use for functions that
  97 /// can fail on a regular basis. Additionally, this function is not guaranteed
  98 /// to catch all panics, see the "Notes" section below.
  99 ///
 100 /// The closure provided is required to adhere to the [`UnwindSafe`] trait to ensure
 101 /// that all captured variables are safe to cross this boundary. The purpose of
 102 /// this bound is to encode the concept of [exception safety][rfc] in the type
 103 /// system. Most usage of this function should not need to worry about this
 104 /// bound as programs are naturally unwind safe without `unsafe` code. If it
 105 /// becomes a problem the [`AssertUnwindSafe`] wrapper struct can be used to quickly
 106 /// assert that the usage here is indeed unwind safe.
 107 ///
 108 /// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
 109 ///
 110 /// # Notes
 111 ///
 112 /// Note that this function **might not catch all panics** in Rust. A panic in
 113 /// Rust is not always implemented via unwinding, but can be implemented by
 114 /// aborting the process as well. This function *only* catches unwinding panics,
 115 /// not those that abort the process.
 116 ///
 117 /// Note that if a custom panic hook has been set, it will be invoked before
 118 /// the panic is caught, before unwinding.
 119 ///
 120 /// Also note that unwinding into Rust code with a foreign exception (e.g.
 121 /// an exception thrown from C++ code) is undefined behavior.
 122 ///
 123 /// # Examples
 124 ///
 125 /// ```
 126 /// use std::panic;
 127 ///
 128 /// let result = panic::catch_unwind(|| {
 129 ///     println!("hello!");
 130 /// });
 131 /// assert!(result.is_ok());
 132 ///
 133 /// let result = panic::catch_unwind(|| {
 134 ///     panic!("oh no!");
 135 /// });
 136 /// assert!(result.is_err());
 137 /// ```
 138 #[stable(feature = "catch_unwind", since = "1.9.0")]
 139 pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> {
 140     unsafe { panicking::r#try(f) }
 141 }
 142
 143 /// Triggers a panic without invoking the panic hook.
 144 ///
 145 /// This is designed to be used in conjunction with [`catch_unwind`] to, for
 146 /// example, carry a panic across a layer of C code.
 147 ///
 148 /// # Notes
 149 ///
 150 /// Note that panics in Rust are not always implemented via unwinding, but they
 151 /// may be implemented by aborting the process. If this function is called when
 152 /// panics are implemented this way then this function will abort the process,
 153 /// not trigger an unwind.
 154 ///
 155 /// # Examples
 156 ///
 157 /// ```should_panic
 158 /// use std::panic;
 159 ///
 160 /// let result = panic::catch_unwind(|| {
 161 ///     panic!("oh no!");
 162 /// });
 163 ///
 164 /// if let Err(err) = result {
 165 ///     panic::resume_unwind(err);
 166 /// }
 167 /// ```
 168 #[stable(feature = "resume_unwind", since = "1.9.0")]
 169 pub fn resume_unwind(payload: Box<dyn Any + Send>) -> ! {
 170     panicking::rust_panic_without_hook(payload)
 171 }
 172
 173 /// Make all future panics abort directly without running the panic hook or unwinding.
 174 ///
 175 /// There is no way to undo this; the effect lasts until the process exits or
 176 /// execs (or the equivalent).
 177 ///
 178 /// # Use after fork
 179 ///
 180 /// This function is particularly useful for calling after `libc::fork`.  After `fork`, in a
 181 /// multithreaded program it is (on many platforms) not safe to call the allocator.  It is also
 182 /// generally highly undesirable for an unwind to unwind past the `fork`, because that results in
 183 /// the unwind propagating to code that was only ever expecting to run in the parent.
 184 ///
 185 /// `panic::always_abort()` helps avoid both of these.  It directly avoids any further unwinding,
 186 /// and if there is a panic, the abort will occur without allocating provided that the arguments to
 187 /// panic can be formatted without allocating.
 188 ///
 189 /// Examples
 190 ///
 191 /// ```no_run
 192 /// #![feature(panic_always_abort)]
 193 /// use std::panic;
 194 ///
 195 /// panic::always_abort();
 196 ///
 197 /// let _ = panic::catch_unwind(|| {
 198 ///     panic!("inside the catch");
 199 /// });
 200 ///
 201 /// // We will have aborted already, due to the panic.
 202 /// unreachable!();
 203 /// ```
 204 #[unstable(feature = "panic_always_abort", issue = "84438")]
 205 pub fn always_abort() {
 206     crate::panicking::panic_count::set_always_abort();
 207 }
 208
 209 /// The configuration for whether and how the default panic hook will capture
 210 /// and display the backtrace.
 211 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 212 #[unstable(feature = "panic_backtrace_config", issue = "93346")]
 213 #[non_exhaustive]
 214 pub enum BacktraceStyle {
 215     /// Prints a terser backtrace which ideally only contains relevant
 216     /// information.
 217     Short,
 218     /// Prints a backtrace with all possible information.
 219     Full,
 220     /// Disable collecting and displaying backtraces.
 221     Off,
 222 }
 223
 224 impl BacktraceStyle {
 225     pub(crate) fn full() -> Option<Self> {
 226         if cfg!(feature = "backtrace") { Some(BacktraceStyle::Full) } else { None }
 227     }
 228
 229     fn as_usize(self) -> usize {
 230         match self {
 231             BacktraceStyle::Short => 1,
 232             BacktraceStyle::Full => 2,
 233             BacktraceStyle::Off => 3,
 234         }
 235     }
 236
 237     fn from_usize(s: usize) -> Option<Self> {
 238         Some(match s {
 239             0 => return None,
 240             1 => BacktraceStyle::Short,
 241             2 => BacktraceStyle::Full,
 242             3 => BacktraceStyle::Off,
 243             _ => unreachable!(),
 244         })
 245     }
 246 }
 247
 248 // Tracks whether we should/can capture a backtrace, and how we should display
 249 // that backtrace.
 250 //
 251 // Internally stores equivalent of an Option<BacktraceStyle>.
 252 static SHOULD_CAPTURE: AtomicUsize = AtomicUsize::new(0);
 253
 254 /// Configure whether the default panic hook will capture and display a
 255 /// backtrace.
 256 ///
 257 /// The default value for this setting may be set by the `RUST_BACKTRACE`
 258 /// environment variable; see the details in [`get_backtrace_style`].
 259 #[unstable(feature = "panic_backtrace_config", issue = "93346")]
 260 pub fn set_backtrace_style(style: BacktraceStyle) {
 261     if !cfg!(feature = "backtrace") {
 262         // If the `backtrace` feature of this crate isn't enabled, skip setting.
 263         return;
 264     }
 265     SHOULD_CAPTURE.store(style.as_usize(), Ordering::Release);
 266 }
 267
 268 /// Checks whether the standard library's panic hook will capture and print a
 269 /// backtrace.
 270 ///
 271 /// This function will, if a backtrace style has not been set via
 272 /// [`set_backtrace_style`], read the environment variable `RUST_BACKTRACE` to
 273 /// determine a default value for the backtrace formatting:
 274 ///
 275 /// The first call to `get_backtrace_style` may read the `RUST_BACKTRACE`
 276 /// environment variable if `set_backtrace_style` has not been called to
 277 /// override the default value. After a call to `set_backtrace_style` or
 278 /// `get_backtrace_style`, any changes to `RUST_BACKTRACE` will have no effect.
 279 ///
 280 /// `RUST_BACKTRACE` is read according to these rules:
 281 ///
 282 /// * `0` for `BacktraceStyle::Off`
 283 /// * `full` for `BacktraceStyle::Full`
 284 /// * `1` for `BacktraceStyle::Short`
 285 /// * Other values are currently `BacktraceStyle::Short`, but this may change in
 286 ///   the future
 287 ///
 288 /// Returns `None` if backtraces aren't currently supported.
 289 #[unstable(feature = "panic_backtrace_config", issue = "93346")]
 290 pub fn get_backtrace_style() -> Option<BacktraceStyle> {
 291     if !cfg!(feature = "backtrace") {
 292         // If the `backtrace` feature of this crate isn't enabled quickly return
 293         // `Unsupported` so this can be constant propagated all over the place
 294         // to optimize away callers.
 295         return None;
 296     }
 297     if let Some(style) = BacktraceStyle::from_usize(SHOULD_CAPTURE.load(Ordering::Acquire)) {
 298         return Some(style);
 299     }
 300
 301     let format = crate::env::var_os("RUST_BACKTRACE")
 302         .map(|x| {
 303             if &x == "0" {
 304                 BacktraceStyle::Off
 305             } else if &x == "full" {
 306                 BacktraceStyle::Full
 307             } else {
 308                 BacktraceStyle::Short
 309             }
 310         })
 311         .unwrap_or(if cfg!(target_os = "fuchsia") {
 312             // Fuchsia components default to full backtrace.
 313             BacktraceStyle::Full
 314         } else {
 315             BacktraceStyle::Off
 316         });
 317     set_backtrace_style(format);
 318     Some(format)
 319 }
 320
 321 #[cfg(test)]
 322 mod tests;