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

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

diff --git a/rayon-core/src/thread_pool/mod.rs b/rayon-core/src/thread_pool/mod.rs
index c37826ef5..0db788771 100644
--- a/rayon-core/src/thread_pool/mod.rs
+++ b/rayon-core/src/thread_pool/mod.rs
@@ -80,6 +80,43 @@ impl ThreadPool {
     /// thread-local data from the current thread will not be
     /// accessible.
     ///
+    /// # Warning: execution order
+    ///
+    /// If the current thread is part of a different thread pool, it will try to
+    /// keep busy while the `op` completes in its target pool, similar to
+    /// calling [`ThreadPool::yield_now()`] in a loop. Therefore, it may
+    /// potentially schedule other tasks to run on the current thread in the
+    /// meantime. For example
+    ///
+    /// ```rust
+    /// # use rayon_core as rayon;
+    /// fn main() {
+    ///     rayon::ThreadPoolBuilder::new().num_threads(1).build_global().unwrap();
+    ///     let pool = rayon_core::ThreadPoolBuilder::default().build().unwrap();
+    ///     let do_it = || {
+    ///         print!("one ");
+    ///         pool.install(||{});
+    ///         print!("two ");
+    ///     }
+    ///     rayon::join(|| do_it(), || do_it());
+    /// }
+    /// ```
+    ///
+    /// Since we configured just one thread in the global pool, one might
+    /// expect `do_it()` to run sequentially, producing:
+    ///
+    /// ```ascii
+    /// one two one two
+    /// ```
+    ///
+    /// However each call to `install()` yields implicitly, allowing rayon to
+    /// run multiple instances of `do_it()` concurrently on the single, global
+    /// thread. The following output would be equally valid:
+    ///
+    /// ```ascii
+    /// one one two two
+    /// ```
+    ///
     /// # Panics
     ///
     /// If `op` should panic, that panic will be propagated.

From 9dc500fbdfaa43229da79ea6bec4e7a4ecf53240 Mon Sep 17 00:00:00 2001
From: Josh Stone <cuviper@gmail.com>
Date: Wed, 13 Dec 2023 08:27:27 -0800
Subject: [PATCH 2/2] Syntax fix in `ThreadPool::install` example

---
 rayon-core/src/thread_pool/mod.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rayon-core/src/thread_pool/mod.rs b/rayon-core/src/thread_pool/mod.rs
index 0db788771..5ae6e0f60 100644
--- a/rayon-core/src/thread_pool/mod.rs
+++ b/rayon-core/src/thread_pool/mod.rs
@@ -97,7 +97,7 @@ impl ThreadPool {
     ///         print!("one ");
     ///         pool.install(||{});
     ///         print!("two ");
-    ///     }
+    ///     };
     ///     rayon::join(|| do_it(), || do_it());
     /// }
     /// ```