Tidy up definition and add docs

Author: alexcrichton

src/symbolize/gimli.rs

@@ -330,7 +330,7 @@ impl Mapping {
 
 type Cache = Vec<(PathBuf, Mapping)>;
 
-/// Warning: this function is not threadsafe and needs to be externally synchronized
+// unsafe because this is required to be externally synchronized
 unsafe fn with_cache(f: impl FnOnce(&mut Cache)) {
     // A very small, very simple LRU cache for debug info mappings.
     //
@@ -347,6 +347,7 @@ unsafe fn with_cache(f: impl FnOnce(&mut Cache)) {
     f(MAPPINGS_CACHE.get_or_insert_with(|| Vec::with_capacity(MAPPINGS_CACHE_SIZE)))
 }
 
+// unsafe because this is required to be externally synchronized
 pub unsafe fn clear_symbol_cache() {
     with_cache(|cache| cache.clear());
 }

src/symbolize/mod.rs

@@ -434,13 +434,35 @@ cfg_if::cfg_if! {
     }
 }
 
+/// Attempt to reclaim that cached memory used to symbolicate addresses.
+///
+/// This method will attempt to release any global data structures that have
+/// otherwise been cached globally or in the thread which typically represent
+/// parsed DWARF information or similar.
+///
+/// # Caveats
+///
+/// While this function is always available it doesn't actually do anything on
+/// most implementations. Libraries like dbghelp or libbacktrace do not provide
+/// facilities to deallocate state and manage the allocated memory. For now the
+/// `gimli-symbolize` feature of this crate is the only feature where this
+/// function has any effect.
+#[cfg(feature = "std")]
+pub fn clear_symbol_cache() {
+    let _guard = crate::lock::lock();
+    unsafe {
+        clear_symbol_cache_imp();
+    }
+}
+
 mod dladdr;
 
 cfg_if::cfg_if! {
     if #[cfg(all(windows, target_env = "msvc", feature = "dbghelp"))] {
         mod dbghelp;
         use self::dbghelp::resolve as resolve_imp;
         use self::dbghelp::Symbol as SymbolImp;
+        unsafe fn clear_symbol_cache_imp() {}
     } else if #[cfg(all(
         feature = "std",
         feature = "gimli-symbolize",
@@ -453,6 +475,7 @@ cfg_if::cfg_if! {
         mod gimli;
         use self::gimli::resolve as resolve_imp;
         use self::gimli::Symbol as SymbolImp;
+        use self::gimli::clear_symbol_cache as clear_symbol_cache_imp;
     // Note that we only enable coresymbolication on iOS when debug assertions
     // are enabled because it's helpful in debug mode but it looks like apps get
     // rejected from the app store if they use this API, see #92 for more info
@@ -462,50 +485,26 @@ cfg_if::cfg_if! {
         mod coresymbolication;
         use self::coresymbolication::resolve as resolve_imp;
         use self::coresymbolication::Symbol as SymbolImp;
+        unsafe fn clear_symbol_cache_imp() {}
     } else if #[cfg(all(feature = "libbacktrace",
                         any(unix, all(windows, not(target_vendor = "uwp"), target_env = "gnu")),
                         not(target_os = "fuchsia"),
                         not(target_os = "emscripten")))] {
         mod libbacktrace;
         use self::libbacktrace::resolve as resolve_imp;
         use self::libbacktrace::Symbol as SymbolImp;
+        unsafe fn clear_symbol_cache_imp() {}
     } else if #[cfg(all(unix,
                         not(target_os = "emscripten"),
                         feature = "dladdr"))] {
         mod dladdr_resolve;
         use self::dladdr_resolve::resolve as resolve_imp;
         use self::dladdr_resolve::Symbol as SymbolImp;
+        unsafe fn clear_symbol_cache_imp() {}
     } else {
         mod noop;
         use self::noop::resolve as resolve_imp;
         use self::noop::Symbol as SymbolImp;
+        unsafe fn clear_symbol_cache_imp() {}
     }
 }
-
-cfg_if::cfg_if! {
-    if #[cfg(all(
-        feature = "std",
-        feature = "gimli-symbolize",
-        any(
-            target_os = "linux",
-            target_os = "macos",
-            windows,
-        ),
-        not(all(windows, target_env = "msvc", feature = "dbghelp")),
-    ))] {
-        /// clear_symbol_cache tries to reclaim that cached memory.
-        /// Note: for now, only the Gimli implementation is able to clear its cache.
-        pub fn clear_symbol_cache() {    
-            let _guard = crate::lock::lock();
-            unsafe {
-                self::gimli::clear_symbol_cache();
-            }
-        }
-    } else if #[cfg(feature = "std")] {
-        /// clear_symbol_cache tries to reclaim that cached memory.
-        /// Note: for now, only the Gimli implementation is able to clear its cache.
-        pub fn clear_symbol_cache() {
-            // noop
-        }
-    }
-}