-
Notifications
You must be signed in to change notification settings - Fork 12.8k
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.
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
Improve std::thread::available_parallelism
docs
#89670
Conversation
This comment has been minimized.
This comment has been minimized.
library/std/src/thread/mod.rs
Outdated
/// - The amount of parallelism available may be _higher_ than the CPU core | ||
/// count when a CPU exposes multiple "hardware threads" per CPU core. | ||
/// - The reported amount of parallelism available may be _higher_ than the CPU | ||
/// core count if a CPU has "Hyper-Threading" enabled. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does it make sense to list these first two as separate points? They're more or less the same as far as the amount of threads that'll execute at the same time is concerned.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed.
I also think we should just de-emphasize "cores" here; these docs are going out of their way to explain how the return value might not be CPU cores, but really, there's no reason it would be "cores". Most commonly, it'll be whatever the OS reports as CPUs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is "CPU" even the thing we want to discuss here? What about GPUs and other possible implementations of computers which Rust may target and for which this function would likely return something else. I really like the summary of this function in that context. It doesn't mention threads or hardware anymore and instead turns the explanation around to be all about the program instead.
For the sake of maintainability (technical documentation debt), I'd recommend to simply omit the whole section on Instead, I'd suggest wording to the effect of IMHO, anybody who is interested in the "fully correct picture on parallelism" will have to study the implementation, anyway (or get this from highly specialized implementation) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Really nice.
library/std/src/thread/mod.rs
Outdated
/// - The amount of parallelism available may be _higher_ than the CPU core | ||
/// count when a CPU exposes multiple "hardware threads" per CPU core. | ||
/// - The reported amount of parallelism available may be _higher_ than the CPU | ||
/// core count if a CPU has "Hyper-Threading" enabled. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is "CPU" even the thing we want to discuss here? What about GPUs and other possible implementations of computers which Rust may target and for which this function would likely return something else. I really like the summary of this function in that context. It doesn't mention threads or hardware anymore and instead turns the explanation around to be all about the program instead.
It looks like @joshtriplett is all over this! Thank you. I think my concern is totally addressed here, so I'll hand things over if you don't mind. |
Finished merging @joshtriplett's suggestions; believe this should be ready for review again! |
@bors r+ 🧵📄👍 |
📌 Commit 1c456bc81310fa0cc6641b239a3102adaa49820f has been approved by |
This comment has been minimized.
This comment has been minimized.
The last run contained a typo in the example which caused the test to fail. Fixed it, and tests now pass. Can someone re-run bors again? Thanks! |
@bors r=joshtriplett |
📌 Commit 21429ed has been approved by |
…askrgr Rollup of 6 pull requests Successful merges: - rust-lang#89347 (suggestion for typoed crate or module) - rust-lang#89670 (Improve `std::thread::available_parallelism` docs) - rust-lang#89757 (Use shallow clones for submodules) - rust-lang#89759 (Assemble the compiler when running `x.py build`) - rust-lang#89846 (Add `riscv32imc-esp-espidf` to 1.56 changelog) - rust-lang#89853 (Update the 1.56.0 release header for consistency) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
…me, r=joshtriplett Add caveat about changing parallelism and function call overhead As discussed in rust-lang#89670 (comment) r? `@joshtriplett`
…me, r=joshtriplett Add caveat about changing parallelism and function call overhead As discussed in rust-lang#89670 (comment) r? ``@joshtriplett``
Tracking issue: #74479
This PR reworks the documentation of
std::thread::available_parallelism
, as requested here.Changes
The following changes are made:
available_parallelism
may return numbers that differ from the number of CPU cores in the host machine.num-cpus
which provides similar functionality toavailable_parallelism
, and is one of the most popular crates on crates.io.Thanks!
r? @BurntSushi