Module std::rt::unwindUnstable

Implementation of Rust stack unwinding

For background on exception handling and stack unwinding please see "Exception Handling in LLVM" (llvm.org/docs/ExceptionHandling.html) and documents linked from it. These are also good reads: http://theofilos.cs.columbia.edu/blog/2013/09/22/base_abi/ http://monoinfinito.wordpress.com/series/exception-handling-in-c/ http://www.airs.com/blog/index.php?s=exception+frames

A brief summary

Exception handling happens in two phases: a search phase and a cleanup phase.

In both phases the unwinder walks stack frames from top to bottom using information from the stack frame unwind sections of the current process's modules ("module" here refers to an OS module, i.e. an executable or a dynamic library).

For each stack frame, it invokes the associated "personality routine", whose address is also stored in the unwind info section.

In the search phase, the job of a personality routine is to examine exception object being thrown, and to decide whether it should be caught at that stack frame. Once the handler frame has been identified, cleanup phase begins.

In the cleanup phase, personality routines invoke cleanup code associated with their stack frames (i.e. destructors). Once stack has been unwound down to the handler frame level, unwinding stops and the last personality routine transfers control to its catch block.

Frame unwind info registration

Each module has its own frame unwind info section (usually ".eh_frame"), and unwinder needs to know about all of them in order for unwinding to be able to cross module boundaries.

On some platforms, like Linux, this is achieved by dynamically enumerating currently loaded modules via the dl_iterate_phdr() API and finding all .eh_frame sections.

Others, like Windows, require modules to actively register their unwind info sections by calling __register_frame_info() API at startup. In the latter case it is essential that there is only one copy of the unwinder runtime in the process. This is usually achieved by linking to the dynamic version of the unwind runtime.

Currently Rust uses unwind runtime provided by libgcc.

Functions

begin_unwind	This is the entry point of unwinding for panic!() and assert!().
begin_unwind_fmt	The entry point for unwinding with a formatted message.
panicking	Determines whether the current thread is unwinding because of panic.
register	Register a callback to be invoked when a thread unwinds.
rust_begin_unwind	Entry point of panic from the libcore crate.
try	Invoke a closure, capturing the cause of panic if one occurs.

Type Definitions

Callback