From: Steve Klabnik <steve@steveklabnik.com>
Date: Tue, 7 Jul 2015 13:35:56 +0000 (-0400)
Subject: Expand a bit on thread::park spurious wakeups
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=cbdc52e9867ce550c2f8a22613106f65cf54a7ef;p=rust.git

Expand a bit on thread::park spurious wakeups

Fixes #26475
---

diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index dbb7d3233bc..3299c848ba7 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -508,9 +508,25 @@ pub fn sleep(dur: Duration) {
     imp::Thread::sleep(dur)
 }
 
-/// Blocks unless or until the current thread's token is made available (may wake spuriously).
+/// Blocks unless or until the current thread's token is made available.
 ///
-/// See the module doc for more detail.
+/// Every thread is equipped with some basic low-level blocking support, via
+/// the `park()` function and the [`unpark()`][unpark] method. These can be
+/// used as a more CPU-efficient implementation of a spinlock.
+///
+/// [unpark]: struct.Thread.html#method.unpark
+///
+/// The API is typically used by acquiring a handle to the current thread,
+/// placing that handle in a shared data structure so that other threads can
+/// find it, and then parking (in a loop with a check for the token actually
+/// being acquired).
+///
+/// A call to `park` does not guarantee that the thread will remain parked
+/// forever, and callers should be prepared for this possibility.
+///
+/// See the [module documentation][thread] for more detail.
+///
+/// [thread]: index.html
 //
 // The implementation currently uses the trivial strategy of a Mutex+Condvar
 // with wakeup flag, which does not actually allow spurious wakeups. In the