Documented thread hooks on panics and errors of thread spawning functions.

library/std/src/thread/builder.rs

@@ -161,12 +161,18 @@ impl Builder {
     /// [`io::Result`] to capture any failure to create the thread at
     /// the OS level.
     ///
-    /// [`io::Result`]: crate::io::Result
+    /// Like [`spawn`], this method will still call the main thread functions
+    /// added by [`add_spawn_hook`] (unless [`Builder::no_hooks`] was called),
+    /// but won't execute the returned functions if thread creation fails at the
+    /// OS level.
     ///
     /// # Panics
     ///
     /// Panics if a thread name was set and it contained null bytes.
     ///
+    /// Unlike the [`spawn`] free function, if it panics for this reason, the
+    /// parent thread functions added by [`add_spawn_hook`] will _not_ be called.
+    ///
     /// # Examples
     ///
     /// ```
@@ -181,8 +187,10 @@ impl Builder {
     /// handler.join().unwrap();
     /// ```
     ///
+    /// [`io::Result`]: crate::io::Result
     /// [`thread::spawn`]: super::spawn
     /// [`spawn`]: super::spawn
+    /// [`add_spawn_hook`]: crate::thread::add_spawn_hook
     #[stable(feature = "rust1", since = "1.0.0")]
     #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
     pub fn spawn<F, T>(self, f: F) -> io::Result<JoinHandle<T>>
@@ -212,10 +220,18 @@ impl Builder {
     /// [`io::Result`] to capture any failure to create the thread at
     /// the OS level.
     ///
+    /// Like [`spawn`], this method will still call the main thread functions
+    /// added by [`add_spawn_hook`] (unless [`Builder::no_hooks`] was called),
+    /// but won't execute the returned functions if thread creation fails at the
+    /// OS level.
+    ///
     /// # Panics
     ///
     /// Panics if a thread name was set and it contained null bytes.
     ///
+    /// Unlike the [`spawn`] free function, if it panics for this reason, the
+    /// parent thread functions added by [`add_spawn_hook`] will _not_ be called.
+    ///
     /// # Safety
     ///
     /// The caller has to ensure that the spawned thread does not outlive any
@@ -253,6 +269,7 @@ impl Builder {
     /// [`io::Result`]: crate::io::Result
     /// [`thread::spawn`]: super::spawn
     /// [`spawn`]: super::spawn
+    /// [`add_spawn_hook`]: crate::thread::add_spawn_hook
     #[stable(feature = "thread_spawn_unchecked", since = "1.82.0")]
     #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
     pub unsafe fn spawn_unchecked<F, T>(self, f: F) -> io::Result<JoinHandle<T>>

library/std/src/thread/functions.rs

@@ -45,8 +45,11 @@ use crate::{io, panicking};
 ///
 /// # Panics
 ///
-/// Panics if the OS fails to create a thread; use [`Builder::spawn`]
-/// to recover from such errors.
+/// Panics if the OS fails to create a thread; use [`Builder::spawn`] to recover
+/// from such errors.
+///
+/// Additionally, if hooks were added via [`add_spawn_hook`], they will still be
+/// called in the parent thread, but the returned functions will not be executed.
 ///
 /// # Examples
 ///
@@ -120,6 +123,7 @@ use crate::{io, panicking};
 /// [`channels`]: crate::sync::mpsc
 /// [`join`]: JoinHandle::join
 /// [`Err`]: crate::result::Result::Err
+/// [`add_spawn_hook`]: crate::thread::add_spawn_hook
 #[stable(feature = "rust1", since = "1.0.0")]
 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
 pub fn spawn<F, T>(f: F) -> JoinHandle<T>

library/std/src/thread/scoped.rs

@@ -193,7 +193,13 @@ impl<'scope, 'env> Scope<'scope, 'env> {
     /// Panics if the OS fails to create a thread; use [`Builder::spawn_scoped`]
     /// to recover from such errors.
     ///
+    /// like the free [`spawn`] function, if hooks were added via [`add_spawn_hook`],
+    /// they will still be called in the parent thread, but the returned functions will
+    /// not be executed.
+    ///
     /// [`join`]: ScopedJoinHandle::join
+    /// [`add_spawn_hook`]: crate::thread::add_spawn_hook
+    /// [`spawn`]: crate::thread::spawn
     #[stable(feature = "scoped_threads", since = "1.63.0")]
     pub fn spawn<F, T>(&'scope self, f: F) -> ScopedJoinHandle<'scope, T>
     where
@@ -210,12 +216,18 @@ impl Builder {
     /// Unlike [`Scope::spawn`], this method yields an [`io::Result`] to
     /// capture any failure to create the thread at the OS level.
     ///
-    /// [`io::Result`]: crate::io::Result
+    /// Like [`Scope::spawn`], this method will still call the main thread functions
+    /// added by [`add_spawn_hook`] (unless [`Builder::no_hooks`] was called),
+    /// but won't execute the returned functions if thread creation fails at the
+    /// OS level.
     ///
     /// # Panics
     ///
     /// Panics if a thread name was set and it contained null bytes.
     ///
+    /// Unlike with [`Scope::spawn`], if it panics for this reason, the hooks
+    /// added by [`add_spawn_hook`] will _not_ be called.
+    ///
     /// # Example
     ///
     /// ```
@@ -251,6 +263,9 @@ impl Builder {
     /// a.push(4);
     /// assert_eq!(x, a.len());
     /// ```
+    ///
+    /// [`io::Result`]: crate::io::Result
+    /// [`add_spawn_hook`]: crate::thread::add_spawn_hook
     #[stable(feature = "scoped_threads", since = "1.63.0")]
     pub fn spawn_scoped<'scope, 'env, F, T>(
         self,