From 7098a714e8dffe32ae10a27a18a3d73b23431a55 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 15 Feb 2022 14:51:24 -0800 Subject: [PATCH] Improve docs for `is_running` to explain use case --- library/std/src/thread/mod.rs | 7 ++++--- library/std/src/thread/scoped.rs | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs index f7af66ae5b51f..0a6a7cfe976cc 100644 --- a/library/std/src/thread/mod.rs +++ b/library/std/src/thread/mod.rs @@ -1487,13 +1487,14 @@ impl JoinHandle { /// 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 4fd076e4a2d4b..a387a09dc8b15 100644 --- a/library/std/src/thread/scoped.rs +++ b/library/std/src/thread/scoped.rs @@ -308,13 +308,14 @@ impl<'scope, T> ScopedJoinHandle<'scope, 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