created_at2022-04-29 14:20:25.53967
updated_at2024-06-08 08:24:00.251099
descriptionAllows running of user code during crash events



🔥 crash-handler

Runs user-specified code when a crash occurs

Embark Embark Docs dependency status Build status


On Linux this is done by handling signals, namely the following.

One important detail of the Linux signal handling is that this crate hooks pthread_create so that an alternate signal stack is always installed on every thread. [std::thread::Thread] already does this, however hooking pthread_create allows us to ensure this occurs for threads created from eg. C/C++ code as well. An alternate stack is necessary to reliably handle a SIGSEGV caused by a stack overflow, as signals are otherwise handled on the same stack that raised the signal.


Signal sent to a process to tell it to abort, i.e. to terminate. The signal is usually initiated by the process itself when it calls std::process::abort or libc::abort, but it can be sent to the process from outside itself like any other signal.


Signal sent to a process when it causes a bus error.


Signal sent to a process when it executes an erroneous arithmetic operation. Though it stands for floating point exception this signal covers integer operations as well.


Signal sent to a process when it attempts to execute an illegal, malformed, unknown, or privileged, instruction.


Signal sent to a process when it makes an invalid virtual memory reference, a segmentation fault. This covers infamous null pointer access, out of bounds access, use after free, stack overflows, etc.


Signal sent to a process when a trap is raised, eg. a breakpoint or debug assertion.


On Windows we catch exceptions, which cover a wide range of crash reasons, as well as invalid parameters and purecall


On Macos we use exception ports. Exception ports are the first layer that exceptions are filtered, from a thread level, to a process (task) level, and finally to a host level.

If no user ports have been registered, the default Macos implementation is to convert the Mach exception into an equivalent Unix signal and deliver it to any registered signal handlers before performing the default action for the exception/signal (ie process termination). This means that if you use this crate in conjunction with signal handling on MacOs, you will not get the results you expect as the exception port used by this crate will take precedence over the signal handler. See this issue for a concrete example.

Note that there is one exception to the above, which is that SIGABRT is handled by a signal handler, as there is no equivalent Mach exception for it.


Covers similar crashes as SIGSEGV and SIGBUS


Covers similar crashes as SIGILL


Covers similar crashes as SIGFPE


Covers similar crashes as SIGTRAP


Contributor Covenant

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started. Please also read our Contributor Terms before you make any contributions.

Any contribution intentionally submitted for inclusion in an Embark Studios project, shall comply with the Rust standard licensing model (MIT OR Apache 2.0) and therefore be dual licensed as described below, without any additional terms or conditions:


This contribution is dual licensed under EITHER OF

at your option.

For clarity, "your" refers to Embark or any other licensee/user of the contribution.

Commit count: 171

cargo fmt