From 4aab32d2107e36b532982649a7e7add46edf6301 Mon Sep 17 00:00:00 2001 From: Aria Desires Date: Mon, 6 Jan 2025 21:12:49 -0500 Subject: [PATCH] Document the behaviour of RUST_MIN_STACK=0 While digging through the code I noticed it went out of its way to distinguish RUST_MIN_STACK=0 from the sentinel value of 0, with no justification given. Then I did some searching and discovered at least one person knew that it made Rust use the platform default stack size to work under valgrind better. [0] This took me deeper into the guts of the platform-specific thread code where indeed i saw comments and/or explicit checks about 0 being a special sentinel to discard the 2MiB default in favour of "whatever the platform thread API wants to pick". These docs are already heavily caveated with "this is platform-specific" so I see no harm in specifying this further-platform-specific behaviour. [0]: https://nest.pijul.com/pijul/pijul/discussions/498 --- library/std/src/thread/mod.rs | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs index 85ee369ca2b66..a8c9d3ba8c534 100644 --- a/library/std/src/thread/mod.rs +++ b/library/std/src/thread/mod.rs @@ -125,9 +125,12 @@ //! ## Stack size //! //! The default stack size is platform-dependent and subject to change. -//! Currently, it is 2 MiB on all Tier-1 platforms. +//! Currently, it is 2 MiB on all Tier-1 platforms to make programs behave more consistently +//! cross-platform (notably Windows would otherwise default to 1MiB stacks). //! -//! There are two ways to manually specify the stack size for spawned threads: +//! You can overload Rust's default stack size with one of the two following methods. +//! Passing 0 to either of them will be treated as a request to instead use the +//! platform's "normal" default stack size (e.g. reverting Windows back to 1MiB stacks). //! //! * Build the thread with [`Builder`] and pass the desired stack size to [`Builder::stack_size`]. //! * Set the `RUST_MIN_STACK` environment variable to an integer representing the desired stack @@ -495,7 +498,11 @@ impl Builder { .unwrap_or(imp::DEFAULT_MIN_STACK_SIZE); // 0 is our sentinel value, so ensure that we'll never see 0 after - // initialization has run + // initialization has run even if RUST_MIN_STACK=0. + // + // Note that a stack size of 0 is actually a meaningful input, as each platform's + // thread implementation is expected to use it as a signal to use the + // platform's "normal" default thread size instead of Rust's preferred one. MIN.store(amt + 1, Ordering::Relaxed); amt });