core: registry: Add some more documentation for use_current_thread.

rayon-core/src/lib.rs

@@ -538,6 +538,28 @@ impl<S> ThreadPoolBuilder<S> {
     }
 
     /// Use the current thread as one of the threads in the pool.
+    ///
+    /// The current thread is guaranteed to be at index 0, and since the thread is not managed by
+    /// rayon, the spawn and exit handlers do not run for that thread.
+    ///
+    /// Note that the current thread won't run the main work-stealing loop, so jobs spawned into
+    /// the thread-pool will generally not be picked up automatically by this thread unless you
+    /// yield to rayon in some way, like via [`yield_now()`], [`yield_local()`], [`scope()`], or
+    /// [`clean_up_use_current_thread()`].
+    ///
+    /// # Panics
+    ///
+    /// This function won't panic itself, but [`ThreadPoolBuilder::build()`] will panic if you've
+    /// called this function and the current thread is already part of another [`ThreadPool`].
+    ///
+    /// # Cleaning up a local thread-pool
+    ///
+    /// In order to properly clean-up the worker thread state, for local thread-pools you should
+    /// call [`clean_up_use_current_thread()`] from the same thread that built the thread-pool.
+    /// See that function's documentation for more details.
+    ///
+    /// This call is not required, but without it the registry will leak even if the pool is
+    /// otherwise terminated.
     pub fn use_current_thread(mut self) -> Self {
         self.use_current_thread = true;
         self

rayon-core/src/thread_pool/mod.rs

@@ -461,23 +461,19 @@ pub fn yield_local() -> Option<Yield> {
     }
 }
 
-/// Cleans up the caller thread that created the pool if
-/// [`ThreadPoolBuilder::use_current_thread()`] was used.
+/// Waits for termination of the thread-pool (if pending), and cleans up resources allocated by
+/// [`ThreadPoolBuilder::use_current_thread()`]. Should only be called from the thread that built
+/// the thread-pool, and only when [`ThreadPoolBuilder::use_current_thread()`] is used.
 ///
-/// Waits for termination of all the local work in the caller thread, if any, and exits the worker
-/// thread.
+/// Calling this function from a thread pool job will block indefinitely.
 ///
-/// Should only be called from the thread that called the thread-pool when [`use_current_thread()`]
-/// is used, to properly destroy the registry.
-///
-/// This call is not required, but without it the registry will leak even if the pool is otherwise
-/// terminated.
-///
-/// Calling this function from a thread pool job will infinitely block.
+/// Calling this function before before the thread-pool has been dropped will cause the thread to
+/// not return control flow to the caller until that happens (stealing work as necessary).
 ///
 /// # Panics
 ///
-/// If the calling thread is no the creator thread of a thread-pool.
+/// If the calling thread is no the creator thread of a thread-pool, or not part of that
+/// thread-pool, via [`ThreadPoolBuilder::use_current_thread()`].
 pub fn clean_up_use_current_thread() {
     unsafe {
         let thread = WorkerThread::current()