diff --git a/library/std/src/thread/builder.rs b/library/std/src/thread/builder.rs index f4abe074ab9d7..a77aa5629c2da 100644 --- a/library/std/src/thread/builder.rs +++ b/library/std/src/thread/builder.rs @@ -161,11 +161,15 @@ 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. + /// Panics if a thread name was set and it contained null bytes. In that case, + /// functions added by [`add_spawn_hook`] won't be called. /// /// # Examples /// @@ -181,8 +185,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(self, f: F) -> io::Result> @@ -212,9 +218,15 @@ 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. + /// Panics if a thread name was set and it contained null bytes. In that case, + /// functions added by [`add_spawn_hook`] won't be called. /// /// # Safety /// @@ -253,6 +265,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(self, f: F) -> io::Result> diff --git a/library/std/src/thread/functions.rs b/library/std/src/thread/functions.rs index a25bae1aae31e..2f2fd6e91ef2f 100644 --- a/library/std/src/thread/functions.rs +++ b/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. +/// +/// If functions 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: F) -> JoinHandle diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs index 301f5e949cac3..bf568b0eca404 100644 --- a/library/std/src/thread/scoped.rs +++ b/library/std/src/thread/scoped.rs @@ -193,7 +193,11 @@ impl<'scope, 'env> Scope<'scope, 'env> { /// Panics if the OS fails to create a thread; use [`Builder::spawn_scoped`] /// to recover from such errors. /// + /// If functions 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 #[stable(feature = "scoped_threads", since = "1.63.0")] pub fn spawn(&'scope self, f: F) -> ScopedJoinHandle<'scope, T> where @@ -210,11 +214,15 @@ 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. + /// Panics if a thread name was set and it contained null bytes. In that case, + /// functions added by [`add_spawn_hook`] won't be called. /// /// # Example /// @@ -251,6 +259,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,