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::{Mutex, RwLock};
   9 use crate::thread::Result;
  10
  11 #[doc(hidden)]
  12 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
  13 #[allow_internal_unstable(libstd_sys_internals, const_format_args, core_panic)]
  14 #[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_2015_macro")]
  15 #[rustc_macro_transparency = "semitransparent"]
  16 pub macro panic_2015 {
  17     () => ({
  18         $crate::rt::begin_panic("explicit panic")
  19     }),
  20     ($msg:expr $(,)?) => ({
  21         $crate::rt::begin_panic($msg)
  22     }),
  23     // Special-case the single-argument case for const_panic.
  24     ("{}", $arg:expr $(,)?) => ({
  25         $crate::rt::panic_display(&$arg)
  26     }),
  27     ($fmt:expr, $($arg:tt)+) => ({
  28         $crate::rt::panic_fmt($crate::const_format_args!($fmt, $($arg)+))
  29     }),
  30 }
  31
  32 #[doc(hidden)]
  33 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
  34 pub use core::panic::panic_2021;
  35
  36 #[stable(feature = "panic_hooks", since = "1.10.0")]
  37 pub use crate::panicking::{set_hook, take_hook};
  38
  39 #[unstable(feature = "panic_update_hook", issue = "92649")]
  40 pub use crate::panicking::update_hook;
  41
  42 #[stable(feature = "panic_hooks", since = "1.10.0")]
  43 pub use core::panic::{Location, PanicInfo};
  44
  45 #[stable(feature = "catch_unwind", since = "1.9.0")]
  46 pub use core::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe};
  47
  48 /// Panic the current thread with the given message as the panic payload.
  49 ///
  50 /// The message can be of any (`Any + Send`) type, not just strings.
  51 ///
  52 /// The message is wrapped in a `Box<'static + Any + Send>`, which can be
  53 /// accessed later using [`PanicInfo::payload`].
  54 ///
  55 /// See the [`panic!`] macro for more information about panicking.
  56 #[stable(feature = "panic_any", since = "1.51.0")]
  57 #[inline]
  58 #[track_caller]
  59 pub fn panic_any<M: 'static + Any + Send>(msg: M) -> ! {
  60     crate::panicking::begin_panic(msg);
  61 }
  62
  63 #[stable(feature = "catch_unwind", since = "1.9.0")]
  64 impl<T: ?Sized> UnwindSafe for Mutex<T> {}
  65 #[stable(feature = "catch_unwind", since = "1.9.0")]
  66 impl<T: ?Sized> UnwindSafe for RwLock<T> {}
  67
  68 #[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
  69 impl<T: ?Sized> RefUnwindSafe for Mutex<T> {}
  70 #[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")]
  71 impl<T: ?Sized> RefUnwindSafe for RwLock<T> {}
  72
  73 // https://github.com/rust-lang/rust/issues/62301
  74 #[stable(feature = "hashbrown", since = "1.36.0")]
  75 impl<K, V, S> UnwindSafe for collections::HashMap<K, V, S>
  76 where
  77     K: UnwindSafe,
  78     V: UnwindSafe,
  79     S: UnwindSafe,
  80 {
  81 }
  82
  83 /// Invokes a closure, capturing the cause of an unwinding panic if one occurs.
  84 ///
  85 /// This function will return `Ok` with the closure's result if the closure
  86 /// does not panic, and will return `Err(cause)` if the closure panics. The
  87 /// `cause` returned is the object with which panic was originally invoked.
  88 ///
  89 /// It is currently undefined behavior to unwind from Rust code into foreign
  90 /// code, so this function is particularly useful when Rust is called from
  91 /// another language (normally C). This can run arbitrary Rust code, capturing a
  92 /// panic and allowing a graceful handling of the error.
  93 ///
  94 /// It is **not** recommended to use this function for a general try/catch
  95 /// mechanism. The [`Result`] type is more appropriate to use for functions that
  96 /// can fail on a regular basis. Additionally, this function is not guaranteed
  97 /// to catch all panics, see the "Notes" section below.
  98 ///
  99 /// The closure provided is required to adhere to the [`UnwindSafe`] trait to ensure
 100 /// that all captured variables are safe to cross this boundary. The purpose of
 101 /// this bound is to encode the concept of [exception safety][rfc] in the type
 102 /// system. Most usage of this function should not need to worry about this
 103 /// bound as programs are naturally unwind safe without `unsafe` code. If it
 104 /// becomes a problem the [`AssertUnwindSafe`] wrapper struct can be used to quickly
 105 /// assert that the usage here is indeed unwind safe.
 106 ///
 107 /// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
 108 ///
 109 /// # Notes
 110 ///
 111 /// Note that this function **might not catch all panics** in Rust. A panic in
 112 /// Rust is not always implemented via unwinding, but can be implemented by
 113 /// aborting the process as well. This function *only* catches unwinding panics,
 114 /// not those that abort the process.
 115 ///
 116 /// Also note that unwinding into Rust code with a foreign exception (e.g.
 117 /// an exception thrown from C++ code) is undefined behavior.
 118 ///
 119 /// # Examples
 120 ///
 121 /// ```
 122 /// use std::panic;
 123 ///
 124 /// let result = panic::catch_unwind(|| {
 125 ///     println!("hello!");
 126 /// });
 127 /// assert!(result.is_ok());
 128 ///
 129 /// let result = panic::catch_unwind(|| {
 130 ///     panic!("oh no!");
 131 /// });
 132 /// assert!(result.is_err());
 133 /// ```
 134 #[stable(feature = "catch_unwind", since = "1.9.0")]
 135 pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> {
 136     unsafe { panicking::r#try(f) }
 137 }
 138
 139 /// Triggers a panic without invoking the panic hook.
 140 ///
 141 /// This is designed to be used in conjunction with [`catch_unwind`] to, for
 142 /// example, carry a panic across a layer of C code.
 143 ///
 144 /// # Notes
 145 ///
 146 /// Note that panics in Rust are not always implemented via unwinding, but they
 147 /// may be implemented by aborting the process. If this function is called when
 148 /// panics are implemented this way then this function will abort the process,
 149 /// not trigger an unwind.
 150 ///
 151 /// # Examples
 152 ///
 153 /// ```should_panic
 154 /// use std::panic;
 155 ///
 156 /// let result = panic::catch_unwind(|| {
 157 ///     panic!("oh no!");
 158 /// });
 159 ///
 160 /// if let Err(err) = result {
 161 ///     panic::resume_unwind(err);
 162 /// }
 163 /// ```
 164 #[stable(feature = "resume_unwind", since = "1.9.0")]
 165 pub fn resume_unwind(payload: Box<dyn Any + Send>) -> ! {
 166     panicking::rust_panic_without_hook(payload)
 167 }
 168
 169 /// Make all future panics abort directly without running the panic hook or unwinding.
 170 ///
 171 /// There is no way to undo this; the effect lasts until the process exits or
 172 /// execs (or the equivalent).
 173 ///
 174 /// # Use after fork
 175 ///
 176 /// This function is particularly useful for calling after `libc::fork`.  After `fork`, in a
 177 /// multithreaded program it is (on many platforms) not safe to call the allocator.  It is also
 178 /// generally highly undesirable for an unwind to unwind past the `fork`, because that results in
 179 /// the unwind propagating to code that was only ever expecting to run in the parent.
 180 ///
 181 /// `panic::always_abort()` helps avoid both of these.  It directly avoids any further unwinding,
 182 /// and if there is a panic, the abort will occur without allocating provided that the arguments to
 183 /// panic can be formatted without allocating.
 184 ///
 185 /// Examples
 186 ///
 187 /// ```no_run
 188 /// #![feature(panic_always_abort)]
 189 /// use std::panic;
 190 ///
 191 /// panic::always_abort();
 192 ///
 193 /// let _ = panic::catch_unwind(|| {
 194 ///     panic!("inside the catch");
 195 /// });
 196 ///
 197 /// // We will have aborted already, due to the panic.
 198 /// unreachable!();
 199 /// ```
 200 #[unstable(feature = "panic_always_abort", issue = "84438")]
 201 pub fn always_abort() {
 202     crate::panicking::panic_count::set_always_abort();
 203 }
 204
 205 #[cfg(test)]
 206 mod tests;