Document implicit yield in install() per rayon-rs#1105

Author: benkay86

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;
+    /// 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.