libs (panic)
panic_handlerWhen a thread panics in Rust, the unwinding runtime currently prints a message to standard error containing the panic argument as well as the filename and line number corresponding to the location from which the panic originated. This RFC proposes a mechanism to allow user code to replace this logic with custom handlers that will run before unwinding begins.
The default behavior is not always ideal for all programs:
The standard library previously supported (in unstable code) the registration of a set of panic handlers. This API had several issues:
A new module, std::panic, will be created with a panic handling API:
/// Unregisters the current panic handler, returning it.
///
/// If no custom handler is registered, the default handler will be returned.
///
/// # Panics
///
/// Panics if called from a panicking thread. Note that this will be a nested
/// panic and therefore abort the process.
pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> { ... }
/// Registers a custom panic handler, replacing any that was previously
/// registered.
///
/// # Panics
///
/// Panics if called from a panicking thread. Note that this will be a nested
/// panic and therefore abort the process.
pub fn set_handler<F>(handler: F) where F: Fn(&PanicInfo) + 'static + Sync + Send { ... }
/// A struct providing information about a panic.
pub struct PanicInfo { ... }
impl PanicInfo {
/// Returns the payload associated with the panic.
///
/// This will commonly, but not always, be a `&'static str` or `String`.
pub fn payload(&self) -> &Any + Send { ... }
/// Returns information about the location from which the panic originated,
/// if available.
pub fn location(&self) -> Option<Location> { ... }
}
/// A struct containing information about the location of a panic.
pub struct Location<'a> { ... }
impl<'a> Location<'a> {
/// Returns the name of the source file from which the panic originated.
pub fn file(&self) -> &str { ... }
/// Returns the line number from which the panic originated.
pub fn line(&self) -> u32 { ... }
}
When a panic occurs, but before unwinding begins, the runtime will call the registered panic handler. After the handler returns, the runtime will then unwind the thread. If a thread panics while panicking (a "double panic"), the panic handler will not be invoked and the process will abort. Note that the thread is considered to be panicking while the panic handler is running, so a panic originating from the panic handler will result in a double panic.
The take_handler method exists to allow for handlers to "chain" by closing
over the previous handler and calling into it:
let old_handler = panic::take_handler();
panic::set_handler(move |info| {
println!("uh oh!");
old_handler(info);
});
This is obviously a racy operation, but as a single global resource, the global panic handler should only be adjusted by applications rather than libraries, most likely early in the startup process.
The implementation of set_handler and take_handler will have to be
carefully synchronized to ensure that a handler is not replaced while executing
in another thread. This can be accomplished in a manner similar to that used
by the log
crate.
take_handler and set_handler will wait until no other threads are currently
running the panic handler, at which point they will atomically swap the handler
out as appropriate.
Note that location will always return Some in the current implementation.
It returns an Option to hedge against possible future changes to the panic
system that would allow a crate to be compiled with location metadata removed
to minimize binary size.
C++ has a
std::set_terminate
function which registers a handler for uncaught exceptions, returning the old
one. The handler takes no arguments.
Python passes uncaught exceptions to the global handler
sys.excepthook
which can be set by user code.
In Java, uncaught exceptions can be
handled
by handlers registered on an individual Thread, by the Thread's,
ThreadGroup, and by a handler registered globally. The handlers are provided
with the Throwable that triggered the handler.
The more infrastructure we add to interact with panics, the more attractive it becomes to use them as a more normal part of control flow.
Panic handlers could be run after a panicking thread has unwound rather than
before. This is perhaps a more intuitive arrangement, and allows catch_panic
to prevent panic handlers from running. However, running handlers before
unwinding allows them access to more context, for example, the ability to take
a stack trace.
PanicInfo::location could be split into PanicInfo::file and
PanicInfo::line to cut down on the API size, though that would require
handlers to deal with weird cases like a line number but no file being
available.
RFC 1100 proposed an API based around thread-local handlers. While there are reasonable use cases for the registration of custom handlers on a per-thread basis, most of the common uses for custom handlers want to have a single set of behavior cover all threads in the process. Being forced to remember to register a handler in every thread spawned in a program is tedious and error prone, and not even possible in many cases for threads spawned in libraries the author has no control over.
While out of scope for this RFC, a future extension could add thread-local handlers on top of the global one proposed here in a straightforward manner.
The implementation could be simplified by altering the API to store, and
take_logger to return, an Arc<Fn(&PanicInfo) + 'static + Sync + Send> or
a bare function pointer. This seems like a somewhat weirder API, however, and
the implementation proposed above should not end up complex enough to justify
the change.
None at the moment.