From 2d46ae7c37a779fe993687e753b7c544bb26dc38 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Thu, 22 Nov 2018 10:54:04 +0100 Subject: [PATCH] expand thread::park explanation --- src/libstd/thread/mod.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 8a845efd413..99f8fa390d2 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -806,9 +806,13 @@ const NOTIFIED: usize = 2; /// In other words, each [`Thread`] acts a bit like a spinlock that can be /// locked and unlocked using `park` and `unpark`. /// +/// Notice that it would be a valid (but inefficient) implementation to make both [`park`] and +/// [`unpark`] NOPs that return immediately. Being unblocked does not imply +/// any synchronization with someone that unparked this thread, it could also be spurious. +/// /// 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 `park`ing. When some desired condition is met, another +/// find it, and then `park`ing in a loop. When some desired condition is met, another /// thread calls [`unpark`] on the handle. /// /// The motivation for this design is twofold: @@ -829,6 +833,7 @@ const NOTIFIED: usize = 2; /// .spawn(|| { /// println!("Parking thread"); /// thread::park(); +/// // We *could* get here spuriously, i.e., way before the 10ms below are over! /// println!("Thread unparked"); /// }) /// .unwrap();