Skip to content

Document the behaviour of RUST_MIN_STACK=0 #135178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document the behaviour of RUST_MIN_STACK=0 #135178

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions library/std/src/thread/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, maybe this is a nitpick but the Windows comment isn't strictly accurate. The default size is linker-defined, which does (on MSVC at least) use 1MiB if not otherwise set but it can be different. So saying 0 means 1MiB on Windows is not necessarily true even now and in the future Rust might opt to use a different value by default.

That said, I'm not sure it's worth going on about /stack here, Maybe it's acceptable to say "1MiB" in a lies to children kind of way.

Copy link
Contributor Author

@Gankra Gankra Jan 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah that's basically the emotional arc I went through. I was sorely tempted to specify "usually" or something.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair. I'm a little bit uncomfortable with std docs that aren't technically correct but it is truthish and it does make sense to mention the 1MiB somewhere as it's something that does trip up cross-platform code (admittedly mostly for the main thread rather than spawning new ones but still).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I posted a couple of suggestions improving this to be more accurate. (The resulting comments need word-wrapping after applying the suggestions.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
//! cross-platform (notably Windows would otherwise default to 1MiB stacks).
//! cross-platform (notably Windows otherwise typically defaults to 1 MiB 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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
//! platform's "normal" default stack size (e.g. reverting Windows back to 1MiB stacks).
//! platform's "normal" default stack size (e.g. reverting Windows back to its own default stack size of typically 1 MiB).

//!
//! * 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
Expand Down Expand Up @@ -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
});
Expand Down
Loading