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

Author: benkay86

rayon-core/src/thread_pool/mod.rs

@@ -80,6 +80,52 @@ 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 do_it(pool: &rayon::ThreadPool) -> () {
+    ///     print!("one ");
+    ///     pool.install(||{});
+    ///     print!("two ");
+    /// }
+    /// fn do_it_x_times(x: i32, pool: &rayon::ThreadPool) -> () {
+    ///     if x > 0 {
+    ///         do_it(pool);
+    ///         rayon::join(
+    ///             || do_it_x_times(x-1, pool),
+    ///             || do_it_x_times(x-2, pool),
+    ///         );
+    ///     }
+    /// }
+    /// fn main() {
+    ///     rayon::ThreadPoolBuilder::new().num_threads(1).build_global().unwrap();
+    ///     let pool = rayon_core::ThreadPoolBuilder::default().build().unwrap();
+    ///     do_it_x_times(3, &pool);
+    /// }
+    /// ```
+    ///
+    /// Since we configured just one thread in the global pool, one might
+    /// expect `do_it()` 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 `do_it()` 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.