#[panic_handler]

#[panic_handler] is used to define the behavior of panic! in #![no_std] applications. The #[panic_handler] attribute must be applied to a function with signature fn(&PanicInfo) -> ! and such function must appear once in the dependency graph of a binary / dylib / cdylib crate. The API of PanicInfo can be found in the API docs.

Given that #![no_std] applications have no standard output and that some #![no_std] applications, e.g. embedded applications, need different panicking behaviors for development and for release it can be helpful to have panic crates, crate that only contain a #[panic_handler]. This way applications can easily swap the panicking behavior by simply linking to a different panic crate.

Below is shown an example where an application has a different panicking behavior depending on whether is compiled using the dev profile (cargo build) or using the release profile (cargo build --release).

  1. // crate: panic-semihosting -- log panic messages to the host stderr using semihosting
  3. #![no_std]
  5. use core::fmt::{Write, self};
  6. use core::panic::PanicInfo;
  8. struct HStderr {
  9.     // ..
  10. #     _0: (),
  11. }
  12. #
  13. # impl HStderr {
  14. #     fn new() -> HStderr { HStderr { _0: () } }
  15. # }
  16. #
  17. # impl fmt::Write for HStderr {
  18. #     fn write_str(&mut self, _: &str) -> fmt::Result { Ok(()) }
  19. # }
  21. #[panic_handler]
  22. fn panic(info: &PanicInfo) -> ! {
  23.     let mut host_stderr = HStderr::new();
  25.     // logs "panicked at '$reason', src/main.rs:27:4" to the host stderr
  26.     writeln!(host_stderr, "{}", info).ok();
  28.     loop {}
  29. }
  1. // crate: panic-halt -- halt the thread on panic; messages are discarded
  3. #![no_std]
  5. use core::panic::PanicInfo;
  7. #[panic_handler]
  8. fn panic(_info: &PanicInfo) -> ! {
  9.     loop {}
  10. }
  1. // crate: app
  3. #![no_std]
  5. // dev profile
  6. #[cfg(debug_assertions)]
  7. extern crate panic_semihosting;
  9. // release profile
  10. #[cfg(not(debug_assertions))]
  11. extern crate panic_halt;
  13. // omitted: other `extern crate`s
  15. fn main() {
  16.     // ..
  17. }