From 4c2ddb33ad9e2dbfc3713438472ca85cb5aefd07 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 23 Mar 2015 14:25:56 -0700 Subject: [PATCH] std: Reexport std::rt::unwind::try in std::thread This commit provides a safe, but unstable interface for the `try` functionality of running a closure and determining whether it panicked or not. There are two primary reasons that this function was previously marked `unsafe`: 1. A vanilla version of this function exposes the problem of exception safety by allowing a bare try/catch in the language. It is not clear whether this concern should be directly tied to `unsafe` in Rust at the API level. At this time, however, the bounds on `ffi::try` require the closure to be both `'static` and `Send` (mirroring those of `thread::spawn`). It may be possible to relax the bounds in the future, but for now it's the level of safety that we're willing to commit to. 2. Panicking while panicking will leak resources by not running destructors. Because panicking is still controlled by the standard library, safeguards remain in place to prevent this from happening. The new API is now called `catch_panic` and is marked as `#[unstable]` for now. --- src/libstd/thread/mod.rs | 49 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 57baeb1fb7486..7e96745d22558 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -434,6 +434,55 @@ pub fn panicking() -> bool { unwind::panicking() } +/// Invoke a closure, capturing the cause of panic if one occurs. +/// +/// This function will return `Ok(())` if the closure does not panic, and will +/// return `Err(cause)` if the closure panics. The `cause` returned is the +/// object with which panic was originally invoked. +/// +/// It is currently undefined behavior to unwind from Rust code into foreign +/// code, so this function is particularly useful when Rust is called from +/// another language (normally C). This can run arbitrary Rust code, capturing a +/// panic and allowing a graceful handling of the error. +/// +/// It is **not** recommended to use this function for a general try/catch +/// mechanism. The `Result` type is more appropriate to use for functions that +/// can fail on a regular basis. +/// +/// The closure provided is required to adhere to the `'static` bound to ensure +/// that it cannot reference data in the parent stack frame, mitigating problems +/// with exception safety. Furthermore, a `Send` bound is also required, +/// providing the same safety guarantees as `thread::spawn` (ensuring the +/// closure is properly isolated from the parent). +/// +/// # Examples +/// +/// ``` +/// # #![feature(catch_panic)] +/// use std::thread; +/// +/// let result = thread::catch_panic(|| { +/// println!("hello!"); +/// }); +/// assert!(result.is_ok()); +/// +/// let result = thread::catch_panic(|| { +/// panic!("oh no!"); +/// }); +/// assert!(result.is_err()); +/// ``` +#[unstable(feature = "catch_panic", reason = "recent API addition")] +pub fn catch_panic(f: F) -> Result + where F: FnOnce() -> R + Send + 'static +{ + let mut result = None; + unsafe { + let result = &mut result; + try!(::rt::unwind::try(move || *result = Some(f()))) + } + Ok(result.unwrap()) +} + /// Put the current thread to sleep for the specified amount of time. /// /// The thread may sleep longer than the duration specified due to scheduling