Allow suppressing panics.

This makes it possible to incrementally adopt tracing-mutex
in a library shared by many binaries in the same project without
having to fix all potential deadlocks in all binaries at once. The
binaries that don't yet have proper lock hygeine can opt-out of
real enforcement until their deadlocks are addressed.

Author: anp

examples/suppressed_panics.rs

@@ -0,0 +1,65 @@
+//! Show what a suppressed crash looks like.
+//!
+//! This shows what a traceback of a cycle detection looks like when panics are suppressed. It is
+//! expected to print the cycle when run in debug mode, because it might deadlock. In release mode,
+//! no tracing is used and the program may do any of the following:
+//!
+//! - Return a random valuation of `a`, `b`, and `c`. The implementation has a race-condition by
+//!   design. I have observed (4, 3, 6), but also (6, 3, 5).
+//! - Deadlock forever.
+//!
+//! One can increase the SLEEP_TIME constant to increase the likelihood of a deadlock to occur. On
+//! my machine, 1ns of sleep time gives about a 50/50 chance of the program deadlocking.
+
+use std::thread;
+use std::time::Duration;
+
+use tracing_mutex::stdsync::Mutex;
+
+fn main() {
+    tracing_mutex::suppress_panics();
+
+    let a = Mutex::new(1);
+    let b = Mutex::new(2);
+    let c = Mutex::new(3);
+
+    // Increase this time to increase the likelihood of a deadlock.
+    const SLEEP_TIME: Duration = Duration::from_nanos(1);
+
+    // Depending on random CPU performance, this section may deadlock, or may return a result. With
+    // tracing enabled, the potential deadlock is always detected and a backtrace should be
+    // produced.
+    thread::scope(|s| {
+        // Create an edge from a to b
+        s.spawn(|| {
+            let a = a.lock().unwrap();
+            thread::sleep(SLEEP_TIME);
+            *b.lock().unwrap() += *a;
+        });
+
+        // Create an edge from b to c
+        s.spawn(|| {
+            let b = b.lock().unwrap();
+            thread::sleep(SLEEP_TIME);
+            *c.lock().unwrap() += *b;
+        });
+
+        // Create an edge from c to a
+        //
+        // N.B. the program can deadlock on any of the three edges, as there is no guarantee which
+        // thread will execute first. Nevertheless, any one of them is guaranteed to print with
+        // tracing enabled.
+        s.spawn(|| {
+            let c = c.lock().unwrap();
+            thread::sleep(SLEEP_TIME);
+            *a.lock().unwrap() += *c;
+        });
+    });
+
+    println!(
+        "{}, {}, {}",
+        a.into_inner().unwrap(),
+        b.into_inner().unwrap(),
+        c.into_inner().unwrap()
+    );
+}

src/lib.rs

@@ -116,6 +116,8 @@ mod reporting;
 pub mod stdsync;
 pub mod util;
 
+pub use reporting::suppress_panics;
+
 thread_local! {
     /// Stack to track which locks are held
     ///
@@ -188,7 +190,7 @@ impl MutexId {
         });
 
         if let Some(cycle) = opt_cycle {
-            panic!("{}", Dep::panic_message(&cycle))
+            reporting::report_cycle(&cycle);
         }
 
         HELD_LOCKS.with(|locks| locks.borrow_mut().push(self.value()));

src/reporting.rs

@@ -6,6 +6,7 @@ use std::backtrace::Backtrace;
 use std::borrow::Cow;
 use std::fmt::Write;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 #[cfg(feature = "backtraces")]
 pub type Dep = MutexDep<Arc<Backtrace>>;
@@ -15,12 +16,32 @@ pub type Dep = MutexDep<()>;
 // Base message to be reported when cycle is detected
 const BASE_MESSAGE: &str = "Found cycle in mutex dependency graph:";
 
+static SHOULD_PANIC: AtomicBool = AtomicBool::new(true);
+
+/// Call this early in main() to suppress panics when a cycle is detected and print the lock cycles
+/// to stderr instead.
+/// 
+/// This is not as useful a mechanism for detecting issues as a panic, but it is useful for
+/// incrementally rolling out usage of tracing-mutex to many programs that use a shared crate.
+pub fn suppress_panics() {
+    SHOULD_PANIC.store(false, Ordering::Relaxed);
+}
+
+pub(crate) fn report_cycle(cycle: &[Dep]) {
+    let message = Dep::message(cycle);
+    if SHOULD_PANIC.load(Ordering::Relaxed) {
+        panic!("{message}");
+    } else {
+        eprintln!("{message}");
+    }
+}
+
 pub trait Reportable: Clone {
     /// Capture the current state
     fn capture() -> Self;
 
     /// Format a trace of state for human readable consumption.
-    fn panic_message(trace: &[Self]) -> Cow<'static, str>;
+    fn message(trace: &[Self]) -> Cow<'static, str>;
 }
 
 #[derive(Clone)]
@@ -35,7 +56,7 @@ impl Reportable for MutexDep<()> {
         Self(())
     }
 
-    fn panic_message(_trace: &[Self]) -> Cow<'static, str> {
+    fn message(_trace: &[Self]) -> Cow<'static, str> {
         Cow::Borrowed(BASE_MESSAGE)
     }
 }
@@ -52,7 +73,7 @@ impl Reportable for MutexDep<Arc<Backtrace>> {
         Self(Arc::new(Backtrace::capture()))
     }
 
-    fn panic_message(trace: &[Self]) -> Cow<'static, str> {
+    fn message(trace: &[Self]) -> Cow<'static, str> {
         let mut message = format!("{BASE_MESSAGE}\n");
 
         for entry in trace {