From 8e2497142a319c2c130eebe60ae158d57fd39f3a Mon Sep 17 00:00:00 2001
From: Benjamin Kay <benjamin@benkay.net>
Date: Wed, 29 Nov 2023 14:12:14 -0600
Subject: [PATCH] Document implicit yield in install() per #1105

---
 rayon-core/src/thread_pool/mod.rs | 35 +++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/rayon-core/src/thread_pool/mod.rs b/rayon-core/src/thread_pool/mod.rs
index c37826ef5..0cc1c6f35 100644
--- a/rayon-core/src/thread_pool/mod.rs
+++ b/rayon-core/src/thread_pool/mod.rs
@@ -80,6 +80,41 @@ impl ThreadPool {
     /// thread-local data from the current thread will not be
     /// accessible.
     ///
+    /// # Warning: execution order
+    ///
+    /// `install()` implicitly calls [`ThreadPool::yield_now()`],
+    /// potentially scheduling another task to run on the current thread. For
+    /// example:
+    ///
+    /// ```rust
+    /// # use rayon_core as rayon;
+    /// use rayon::iter::{IntoParallelIterator, ParallelIterator};
+    /// fn main() {
+    ///     rayon::ThreadPoolBuilder::new().num_threads(1).build_global().unwrap();
+    ///     let pool = rayon::ThreadPoolBuilder::default().build().unwrap();
+    ///     (0..3).into_par_iter().for_each(|_| {
+    ///         print!("one ");
+    ///         pool.install(||{});
+    ///         print!("two ");
+    ///     });
+    /// }
+    /// ```
+    ///
+    /// Since we configured just one thread in the global pool, one might
+    /// expect this to run sequentially, producing:
+    ///
+    /// ```ascii
+    /// one two one two one two
+    /// ```
+    ///
+    /// However each call to `install()` yields implicitly, allowing rayon to
+    /// run several instances of the `for_each()` loop concurrently on the
+    /// single, global thread. The following output would be equally valid:
+    ///
+    /// ```ascii
+    /// one one two one two two
+    /// ```
+    ///
     /// # Panics
     ///
     /// If `op` should panic, that panic will be propagated.