diff --git a/library/std/src/thread/builder.rs b/library/std/src/thread/builder.rs index baec8c905d802..e01e2b4b87b93 100644 --- a/library/std/src/thread/builder.rs +++ b/library/std/src/thread/builder.rs @@ -160,10 +160,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. + /// /// # Examples /// /// ``` @@ -178,8 +186,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> @@ -209,10 +219,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 @@ -249,6 +267,7 @@ impl Builder { /// /// [`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 95d7aaf518408..0f49f2df3af6a 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. +/// +/// 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: F) -> JoinHandle diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs index 929f7fdc6dcac..93973bfbd9d50 100644 --- a/library/std/src/thread/scoped.rs +++ b/library/std/src/thread/scoped.rs @@ -196,7 +196,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(&'scope self, f: F) -> ScopedJoinHandle<'scope, T> where @@ -213,10 +219,18 @@ impl Builder { /// Unlike [`Scope::spawn`], this method yields an [`io::Result`] to /// capture any failure to create the thread at the OS level. /// + /// 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 /// /// ``` @@ -252,6 +266,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,