1 Panics the current thread.
3 This allows a program to terminate immediately and provide feedback
4 to the caller of the program.
6 This macro is the perfect way to assert conditions in example code and in
7 tests. `panic!` is closely tied with the `unwrap` method of both
8 [`Option`][ounwrap] and [`Result`][runwrap] enums. Both implementations call
9 `panic!` when they are set to [`None`] or [`Err`] variants.
11 When using `panic!()` you can specify a string payload, that is built using
12 the [`format!`] syntax. That payload is used when injecting the panic into
13 the calling Rust thread, causing the thread to panic entirely.
15 The behavior of the default `std` hook, i.e. the code that runs directly
16 after the panic is invoked, is to print the message payload to
17 `stderr` along with the file/line/column information of the `panic!()`
18 call. You can override the panic hook using [`std::panic::set_hook()`].
19 Inside the hook a panic can be accessed as a `&dyn Any + Send`,
20 which contains either a `&str` or `String` for regular `panic!()` invocations.
21 To panic with a value of another other type, [`panic_any`] can be used.
23 See also the macro [`compile_error!`], for raising errors during compilation.
25 # When to use `panic!` vs `Result`
27 The Rust model of error handling groups errors into two major categories:
28 recoverable and unrecoverable errors. For a recoverable error, such as a file
29 not found error, it’s reasonable to report the problem to the user and retry
30 the operation. Unrecoverable errors are always symptoms of bugs, like trying to
31 access a location beyond the end of an array.
33 The Rust language and standard library provides `Result` and `panic!` as parts
34 of two complementary systems for representing, reporting, propagating, reacting
35 to, and discarding errors for in these two categories.
37 The `panic!` macro is provided to represent unrecoverable errors, whereas the
38 `Result` enum is provided to represent recoverable errors. For more detailed
39 information about error handling check out the [book] or the [`std::result`]
42 [ounwrap]: Option::unwrap
43 [runwrap]: Result::unwrap
44 [`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html
45 [`panic_any`]: ../std/panic/fn.panic_any.html
46 [`Box`]: ../std/boxed/struct.Box.html
47 [`Any`]: crate::any::Any
48 [`format!`]: ../std/macro.format.html
49 [book]: ../book/ch09-00-error-handling.html
50 [`std::result`]: ../std/result/index.html
52 # Current implementation
54 If the main thread panics it will terminate all your threads and end your
55 program with code `101`.
60 # #![allow(unreachable_code)]
62 panic!("this is a terrible mistake!");
63 panic!("this is a {} {message}", "fancy", message = "message");
64 std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere