Improve docs for `is_running` to explain use case

diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs
index f7af66ae5b51f77f68aff283b2e08c779af63c44..0a6a7cfe976cc31b9bb6344793bb42f9f3769f6a 100644 (file)
--- a/library/std/src/thread/mod.rs
+++ b/library/std/src/thread/mod.rs
@@ -1487,13 +1487,14 @@ pub fn join(self) -> Result<T> {
 
     /// Checks if the associated thread has finished running its main function.
     ///
+    /// `is_finished` supports implementing a non-blocking join operation, by checking
+    /// `is_finished`, and calling `join` if it returns `true`. This function does not block. To
+    /// block while waiting on the thread to finish, use [`join`][Self::join].
+    ///
     /// This might return `true` for a brief moment after the thread's main
     /// function has returned, but before the thread itself has stopped running.
     /// However, once this returns `true`, [`join`][Self::join] can be expected
     /// to return quickly, without blocking for any significant amount of time.
-    ///
-    /// This function does not block. To block while waiting on the thread to finish,
-    /// use [`join`][Self::join].
     #[stable(feature = "thread_is_running", since = "1.61.0")]
     pub fn is_finished(&self) -> bool {
         Arc::strong_count(&self.0.packet) == 1

diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs
index 4fd076e4a2d4be477070e26855fe9deb4f66a1c2..a387a09dc8b156813a956f7bad47272ee533665c 100644 (file)
--- a/library/std/src/thread/scoped.rs
+++ b/library/std/src/thread/scoped.rs
@@ -308,13 +308,14 @@ pub fn join(self) -> Result<T> {
 
     /// Checks if the associated thread has finished running its main function.
     ///
+    /// `is_finished` supports implementing a non-blocking join operation, by checking
+    /// `is_finished`, and calling `join` if it returns `false`. This function does not block. To
+    /// block while waiting on the thread to finish, use [`join`][Self::join].
+    ///
     /// This might return `true` for a brief moment after the thread's main
     /// function has returned, but before the thread itself has stopped running.
     /// However, once this returns `true`, [`join`][Self::join] can be expected
     /// to return quickly, without blocking for any significant amount of time.
-    ///
-    /// This function does not block. To block while waiting on the thread to finish,
-    /// use [`join`][Self::join].
     #[stable(feature = "scoped_threads", since = "1.63.0")]
     pub fn is_finished(&self) -> bool {
         Arc::strong_count(&self.0.packet) == 1