From 12efc9d0faefdd18e715690c7ae30908d92b8fc5 Mon Sep 17 00:00:00 2001 From: Felix Raimundo Date: Sun, 7 May 2017 16:49:18 +0200 Subject: [PATCH] Improve `thread::panicking` documentaion. Part of #29378 --- src/libstd/thread/mod.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 4cbcfdbc2d7..04cd28df445 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -458,6 +458,16 @@ pub fn yield_now() { /// Determines whether the current thread is unwinding because of panic. /// +/// A common use of this feature is to poison shared resources when writing +/// unsafe code, by checking `panicking` when the `drop` is called. +/// +/// This is usually not needed when writing safe code, as [`Mutex`es][Mutex] +/// already poison themselves when a thread panics while holding the lock. +/// +/// This can also be used in multithreaded applications, in order to send a +/// message to other threads warning that a thread has panicked (e.g. for +/// monitoring purposes). +/// /// # Examples /// /// ```should_panic @@ -486,6 +496,8 @@ pub fn yield_now() { /// panic!() /// } /// ``` +/// +/// [Mutex]: ../../std/sync/struct.Mutex.html #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn panicking() -> bool { -- 2.44.0