1 //! Panic support in the standard library.
3 #![stable(feature = "core_panic_info", since = "1.41.0")]
9 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
10 #[allow_internal_unstable(core_panic)]
11 #[rustc_diagnostic_item = "core_panic_2015_macro"]
12 #[rustc_macro_transparency = "semitransparent"]
13 pub macro panic_2015 {
15 $crate::panicking::panic("explicit panic")
17 ($msg:literal $(,)?) => (
18 $crate::panicking::panic($msg)
20 ($msg:expr $(,)?) => (
21 $crate::panicking::panic_str($msg)
23 ($fmt:expr, $($arg:tt)+) => (
24 $crate::panicking::panic_fmt($crate::format_args!($fmt, $($arg)+))
29 #[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")]
30 #[allow_internal_unstable(core_panic)]
31 #[rustc_diagnostic_item = "core_panic_2021_macro"]
32 #[rustc_macro_transparency = "semitransparent"]
33 pub macro panic_2021 {
35 $crate::panicking::panic("explicit panic")
38 $crate::panicking::panic_fmt($crate::format_args!($($t)+))
42 /// A struct providing information about a panic.
44 /// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`]
47 /// [`set_hook`]: ../../std/panic/fn.set_hook.html
54 /// panic::set_hook(Box::new(|panic_info| {
55 /// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
56 /// println!("panic occurred: {:?}", s);
58 /// println!("panic occurred");
62 /// panic!("Normal panic");
64 #[lang = "panic_info"]
65 #[stable(feature = "panic_hooks", since = "1.10.0")]
67 pub struct PanicInfo<'a> {
68 payload: &'a (dyn Any + Send),
69 message: Option<&'a fmt::Arguments<'a>>,
70 location: &'a Location<'a>,
73 impl<'a> PanicInfo<'a> {
75 feature = "panic_internals",
76 reason = "internal details of the implementation of the `panic!` and related macros",
81 pub fn internal_constructor(
82 message: Option<&'a fmt::Arguments<'a>>,
83 location: &'a Location<'a>,
86 PanicInfo { location, message, payload: &NoPayload }
90 feature = "panic_internals",
91 reason = "internal details of the implementation of the `panic!` and related macros",
96 pub fn set_payload(&mut self, info: &'a (dyn Any + Send)) {
100 /// Returns the payload associated with the panic.
102 /// This will commonly, but not always, be a `&'static str` or [`String`].
104 /// [`String`]: ../../std/string/struct.String.html
111 /// panic::set_hook(Box::new(|panic_info| {
112 /// if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
113 /// println!("panic occurred: {:?}", s);
115 /// println!("panic occurred");
119 /// panic!("Normal panic");
121 #[stable(feature = "panic_hooks", since = "1.10.0")]
122 pub fn payload(&self) -> &(dyn Any + Send) {
126 /// If the `panic!` macro from the `core` crate (not from `std`)
127 /// was used with a formatting string and some additional arguments,
128 /// returns that message ready to be used for example with [`fmt::write`]
129 #[unstable(feature = "panic_info_message", issue = "66745")]
130 pub fn message(&self) -> Option<&fmt::Arguments<'_>> {
134 /// Returns information about the location from which the panic originated,
137 /// This method will currently always return [`Some`], but this may change
138 /// in future versions.
145 /// panic::set_hook(Box::new(|panic_info| {
146 /// if let Some(location) = panic_info.location() {
147 /// println!("panic occurred in file '{}' at line {}",
152 /// println!("panic occurred but can't get location information...");
156 /// panic!("Normal panic");
158 #[stable(feature = "panic_hooks", since = "1.10.0")]
159 pub fn location(&self) -> Option<&Location<'_>> {
160 // NOTE: If this is changed to sometimes return None,
161 // deal with that case in std::panicking::default_hook and std::panicking::begin_panic_fmt.
166 #[stable(feature = "panic_hook_display", since = "1.26.0")]
167 impl fmt::Display for PanicInfo<'_> {
168 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
169 formatter.write_str("panicked at ")?;
170 if let Some(message) = self.message {
171 write!(formatter, "'{}', ", message)?
172 } else if let Some(payload) = self.payload.downcast_ref::<&'static str>() {
173 write!(formatter, "'{}', ", payload)?
175 // NOTE: we cannot use downcast_ref::<String>() here
176 // since String is not available in libcore!
177 // The payload is a String when `std::panic!` is called with multiple arguments,
178 // but in that case the message is also available.
180 self.location.fmt(formatter)
184 /// A struct containing information about the location of a panic.
186 /// This structure is created by [`PanicInfo::location()`].
193 /// panic::set_hook(Box::new(|panic_info| {
194 /// if let Some(location) = panic_info.location() {
195 /// println!("panic occurred in file '{}' at line {}", location.file(), location.line());
197 /// println!("panic occurred but can't get location information...");
201 /// panic!("Normal panic");
206 /// Comparisons for equality and ordering are made in file, line, then column priority.
207 /// Files are compared as strings, not `Path`, which could be unexpected.
208 /// See [`Location::file`]'s documentation for more discussion.
209 #[lang = "panic_location"]
210 #[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
211 #[stable(feature = "panic_hooks", since = "1.10.0")]
212 pub struct Location<'a> {
218 impl<'a> Location<'a> {
219 /// Returns the source location of the caller of this function. If that function's caller is
220 /// annotated then its call location will be returned, and so on up the stack to the first call
221 /// within a non-tracked function body.
226 /// use std::panic::Location;
228 /// /// Returns the [`Location`] at which it is called.
230 /// fn get_caller_location() -> &'static Location<'static> {
231 /// Location::caller()
234 /// /// Returns a [`Location`] from within this function's definition.
235 /// fn get_just_one_location() -> &'static Location<'static> {
236 /// get_caller_location()
239 /// let fixed_location = get_just_one_location();
240 /// assert_eq!(fixed_location.file(), file!());
241 /// assert_eq!(fixed_location.line(), 14);
242 /// assert_eq!(fixed_location.column(), 5);
244 /// // running the same untracked function in a different location gives us the same result
245 /// let second_fixed_location = get_just_one_location();
246 /// assert_eq!(fixed_location.file(), second_fixed_location.file());
247 /// assert_eq!(fixed_location.line(), second_fixed_location.line());
248 /// assert_eq!(fixed_location.column(), second_fixed_location.column());
250 /// let this_location = get_caller_location();
251 /// assert_eq!(this_location.file(), file!());
252 /// assert_eq!(this_location.line(), 28);
253 /// assert_eq!(this_location.column(), 21);
255 /// // running the tracked function in a different location produces a different value
256 /// let another_location = get_caller_location();
257 /// assert_eq!(this_location.file(), another_location.file());
258 /// assert_ne!(this_location.line(), another_location.line());
259 /// assert_ne!(this_location.column(), another_location.column());
261 #[stable(feature = "track_caller", since = "1.46.0")]
262 #[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
264 pub const fn caller() -> &'static Location<'static> {
265 crate::intrinsics::caller_location()
269 impl<'a> Location<'a> {
271 feature = "panic_internals",
272 reason = "internal details of the implementation of the `panic!` and related macros",
276 pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self {
277 Location { file, line, col }
280 /// Returns the name of the source file from which the panic originated.
282 /// # `&str`, not `&Path`
284 /// The returned name refers to a source path on the compiling system, but it isn't valid to
285 /// represent this directly as a `&Path`. The compiled code may run on a different system with
286 /// a different `Path` implementation than the system providing the contents and this library
287 /// does not currently have a different "host path" type.
289 /// The most surprising behavior occurs when "the same" file is reachable via multiple paths in
290 /// the module system (usually using the `#[path = "..."]` attribute or similar), which can
291 /// cause what appears to be identical code to return differing values from this function.
293 /// # Cross-compilation
295 /// This value is not suitable for passing to `Path::new` or similar constructors when the host
296 /// platform and target platform differ.
303 /// panic::set_hook(Box::new(|panic_info| {
304 /// if let Some(location) = panic_info.location() {
305 /// println!("panic occurred in file '{}'", location.file());
307 /// println!("panic occurred but can't get location information...");
311 /// panic!("Normal panic");
313 #[stable(feature = "panic_hooks", since = "1.10.0")]
314 pub fn file(&self) -> &str {
318 /// Returns the line number from which the panic originated.
325 /// panic::set_hook(Box::new(|panic_info| {
326 /// if let Some(location) = panic_info.location() {
327 /// println!("panic occurred at line {}", location.line());
329 /// println!("panic occurred but can't get location information...");
333 /// panic!("Normal panic");
335 #[stable(feature = "panic_hooks", since = "1.10.0")]
336 pub fn line(&self) -> u32 {
340 /// Returns the column from which the panic originated.
347 /// panic::set_hook(Box::new(|panic_info| {
348 /// if let Some(location) = panic_info.location() {
349 /// println!("panic occurred at column {}", location.column());
351 /// println!("panic occurred but can't get location information...");
355 /// panic!("Normal panic");
357 #[stable(feature = "panic_col", since = "1.25.0")]
358 pub fn column(&self) -> u32 {
363 #[stable(feature = "panic_hook_display", since = "1.26.0")]
364 impl fmt::Display for Location<'_> {
365 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
366 write!(formatter, "{}:{}:{}", self.file, self.line, self.col)
370 /// An internal trait used by libstd to pass data from libstd to `panic_unwind`
371 /// and other panic runtimes. Not intended to be stabilized any time soon, do
373 #[unstable(feature = "std_internals", issue = "none")]
375 pub unsafe trait BoxMeUp {
376 /// Take full ownership of the contents.
377 /// The return type is actually `Box<dyn Any + Send>`, but we cannot use `Box` in libcore.
379 /// After this method got called, only some dummy default value is left in `self`.
380 /// Calling this method twice, or calling `get` after calling this method, is an error.
382 /// The argument is borrowed because the panic runtime (`__rust_start_panic`) only
383 /// gets a borrowed `dyn BoxMeUp`.
384 fn take_box(&mut self) -> *mut (dyn Any + Send);
386 /// Just borrow the contents.
387 fn get(&mut self) -> &(dyn Any + Send);