Document panic-related caveats

Make sure that it's documented that if `cb` ever panics it may abort the
process on some platforms due to restrictions of the C libraries that
we're using.

Author: alexcrichton

src/backtrace/mod.rs

@@ -27,6 +27,13 @@ use types::c_void;
 /// This function requires the `std` feature of the `backtrace` crate to be
 /// enabled, and the `std` feature is enabled by default.
 ///
+/// # Panics
+///
+/// This function strives to never panic, but if the `cb` provided panics then
+/// some platforms will force a double abort to abort the process. Some
+/// platforms use a C library which internally uses callbacks which cannot be
+/// unwound through, so panicking from `cb` may trigger a process abort.
+///
 /// # Example
 ///
 /// ```
@@ -51,6 +58,10 @@ pub fn trace<F: FnMut(&Frame) -> bool>(cb: F) {
 /// This function does not have synchronization guarentees but is available
 /// when the `std` feature of this crate isn't compiled in. See the `trace`
 /// function for more documentation and examples.
+///
+/// # Panics
+///
+/// See information on `trace` for caveats on `cb` panicking.
 pub unsafe fn trace_unsynchronized<F: FnMut(&Frame) -> bool>(mut cb: F) {
     trace_imp(&mut cb)
 }

src/symbolize/libbacktrace.rs

@@ -167,6 +167,8 @@ extern "C" fn syminfo_cb(
     _symval: uintptr_t,
     _symsize: uintptr_t,
 ) {
+    let mut bomb = ::Bomb { enabled: true };
+
     // Once this callback is invoked from `backtrace_syminfo` when we start
     // resolving we go further to call `backtrace_pcinfo`. The
     // `backtrace_pcinfo` function will consult debug information and attemp tto
@@ -189,16 +191,16 @@ extern "C" fn syminfo_cb(
             &mut pcinfo_state as *mut _ as *mut _,
         );
         if !pcinfo_state.called {
-            let mut bomb = ::Bomb { enabled: true };
             (pcinfo_state.cb)(&super::Symbol {
                 inner: Symbol::Syminfo {
                     pc: pc,
                     symname: symname,
                 },
             });
-            bomb.enabled = false;
         }
     }
+
+    bomb.enabled = false;
 }
 
 /// Type of the `data` pointer passed into `pcinfo_cb`
@@ -215,12 +217,13 @@ extern "C" fn pcinfo_cb(
     lineno: c_int,
     function: *const c_char,
 ) -> c_int {
+    if filename.is_null() || function.is_null() {
+        return -1;
+    }
+    let mut bomb = ::Bomb { enabled: true };
+
     unsafe {
-        if filename.is_null() || function.is_null() {
-            return -1;
-        }
         let state = &mut *(data as *mut PcinfoState);
-        let mut bomb = ::Bomb { enabled: true };
         state.called = true;
         (state.cb)(&super::Symbol {
             inner: Symbol::Pcinfo {
@@ -231,10 +234,10 @@ extern "C" fn pcinfo_cb(
                 function,
             },
         });
-        bomb.enabled = false;
-
-        return 0;
     }
+
+    bomb.enabled = false;
+    return 0;
 }
 
 // The libbacktrace API supports creating a state, but it does not

src/symbolize/mod.rs

@@ -33,6 +33,13 @@ use backtrace::Frame;
 /// This function requires the `std` feature of the `backtrace` crate to be
 /// enabled, and the `std` feature is enabled by default.
 ///
+/// # Panics
+///
+/// This function strives to never panic, but if the `cb` provided panics then
+/// some platforms will force a double abort to abort the process. Some
+/// platforms use a C library which internally uses callbacks which cannot be
+/// unwound through, so panicking from `cb` may trigger a process abort.
+///
 /// # Example
 ///
 /// ```
@@ -70,6 +77,13 @@ pub fn resolve<F: FnMut(&Symbol)>(addr: *mut c_void, cb: F) {
 /// This function requires the `std` feature of the `backtrace` crate to be
 /// enabled, and the `std` feature is enabled by default.
 ///
+/// # Panics
+///
+/// This function strives to never panic, but if the `cb` provided panics then
+/// some platforms will force a double abort to abort the process. Some
+/// platforms use a C library which internally uses callbacks which cannot be
+/// unwound through, so panicking from `cb` may trigger a process abort.
+///
 /// # Example
 ///
 /// ```
@@ -111,6 +125,10 @@ impl<'a> ResolveWhat<'a> {
 /// This function does not have synchronization guarentees but is available when
 /// the `std` feature of this crate isn't compiled in. See the `resolve`
 /// function for more documentation and examples.
+///
+/// # Panics
+///
+/// See information on `resolve` for caveats on `cb` panicking.
 pub unsafe fn resolve_unsynchronized<F>(addr: *mut c_void, mut cb: F)
 where
     F: FnMut(&Symbol),
@@ -123,6 +141,10 @@ where
 /// This function does not have synchronization guarentees but is available
 /// when the `std` feature of this crate isn't compiled in. See the
 /// `resolve_frame` function for more documentation and examples.
+///
+/// # Panics
+///
+/// See information on `resolve_frame` for caveats on `cb` panicking.
 pub unsafe fn resolve_frame_unsynchronized<F>(frame: &Frame, mut cb: F)
 where
     F: FnMut(&Symbol),