From d3e4f2b2794932ca742a1678d76abfe9cc76557d Mon Sep 17 00:00:00 2001 From: AhoyISki Date: Fri, 12 Dec 2025 16:00:29 -0300 Subject: [PATCH 1/5] Added documentation about thread hooks to panics and errors in thread spawning functions. --- library/std/src/thread/builder.rs | 19 ++++++++++++++++++- library/std/src/thread/functions.rs | 8 ++++++-- library/std/src/thread/scoped.rs | 17 ++++++++++++++++- 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/library/std/src/thread/builder.rs b/library/std/src/thread/builder.rs index f4abe074ab9d7..c48f21595a889 100644 --- a/library/std/src/thread/builder.rs +++ b/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(self, f: F) -> io::Result> @@ -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(self, f: F) -> io::Result> diff --git a/library/std/src/thread/functions.rs b/library/std/src/thread/functions.rs index a25bae1aae31e..9c84f0168e3ac 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 301f5e949cac3..01f9c7f36c31b 100644 --- a/library/std/src/thread/scoped.rs +++ b/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(&'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, From a7185e9f3bc73bce903dc511a9433422daae494d Mon Sep 17 00:00:00 2001 From: ahoyiski <91404038+AhoyISki@users.noreply.github.com> Date: Fri, 12 Dec 2025 19:25:47 -0300 Subject: [PATCH 2/5] Documentation rephrasing --- library/std/src/thread/builder.rs | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/library/std/src/thread/builder.rs b/library/std/src/thread/builder.rs index c48f21595a889..a77aa5629c2da 100644 --- a/library/std/src/thread/builder.rs +++ b/library/std/src/thread/builder.rs @@ -168,10 +168,8 @@ impl Builder { /// /// # 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. + /// 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 /// @@ -227,10 +225,8 @@ impl Builder { /// /// # 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. + /// 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 /// From 8f0a1ce720402c3909bda64e1a6293fd7965d511 Mon Sep 17 00:00:00 2001 From: ahoyiski <91404038+AhoyISki@users.noreply.github.com> Date: Fri, 12 Dec 2025 19:26:09 -0300 Subject: [PATCH 3/5] Documentation rephrasing --- library/std/src/thread/scoped.rs | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs index 01f9c7f36c31b..301f7e147ad9d 100644 --- a/library/std/src/thread/scoped.rs +++ b/library/std/src/thread/scoped.rs @@ -193,9 +193,8 @@ 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. + /// 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 @@ -223,10 +222,8 @@ impl Builder { /// /// # 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. + /// 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 /// From d3a7384741aa86d1b8be4aab7ebaec279c290ce8 Mon Sep 17 00:00:00 2001 From: ahoyiski <91404038+AhoyISki@users.noreply.github.com> Date: Fri, 12 Dec 2025 19:26:31 -0300 Subject: [PATCH 4/5] Documentation rephrasing Reword documentation for clarity regarding spawn hooks. --- library/std/src/thread/functions.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/std/src/thread/functions.rs b/library/std/src/thread/functions.rs index 9c84f0168e3ac..2f2fd6e91ef2f 100644 --- a/library/std/src/thread/functions.rs +++ b/library/std/src/thread/functions.rs @@ -48,8 +48,8 @@ use crate::{io, panicking}; /// 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. +/// 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 /// From 9a7daa3ff88bb6afcfedacc983be02960b2c152c Mon Sep 17 00:00:00 2001 From: ahoyiski <91404038+AhoyISki@users.noreply.github.com> Date: Fri, 12 Dec 2025 19:28:44 -0300 Subject: [PATCH 5/5] Remove unused `spawn` reference in scoped.rs Removed unused documentation reference to `spawn` in scoped thread. --- library/std/src/thread/scoped.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs index 301f7e147ad9d..bf568b0eca404 100644 --- a/library/std/src/thread/scoped.rs +++ b/library/std/src/thread/scoped.rs @@ -198,7 +198,6 @@ impl<'scope, 'env> Scope<'scope, 'env> { /// /// [`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