Rollup merge of #89324 - yoshuawuyts:hardware-parallelism, r=m-ou-se

Rename `std:🧵:available_conccurrency` to `std:🧵:available_parallelism`

_Tracking issue: https://github.com/rust-lang/rust/issues/74479_

This PR renames  `std:🧵:available_conccurrency` to `std:🧵:available_parallelism`.

## Rationale

The API was initially named `std:🧵:hardware_concurrency`, mirroring the [C++ API of the same name](https://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency). We eventually decided to omit any reference to the word "hardware" after [this comment](https://github.com/rust-lang/rust/pull/74480#issuecomment-662045841). And so we ended up with `available_concurrency` instead.

---

For a talk I was preparing this week I was reading through ["Understanding and expressing scalable concurrency" (A. Turon, 2013)](http://aturon.github.io/academic/turon-thesis.pdf), and the following passage stood out to me (emphasis mine):

> __Concurrency is a system-structuring mechanism.__ An interactive system that deals with disparate asynchronous events is naturally structured by division into concurrent threads with disparate responsibilities. Doing so creates a better fit between problem and solution, and can also decrease the average latency of the system by preventing long-running computations from obstructing quicker ones.

> __Parallelism is a resource.__ A given machine provides a certain capacity for parallelism, i.e., a bound on the number of computations it can perform simultaneously. The goal is to maximize throughput by intelligently using this resource. For interactive systems, parallelism can decrease latency as well.

_Chapter 2.1: Concurrency is not Parallelism. Page 30._

---

_"Concurrency is a system-structuring mechanism. Parallelism is a resource."_ — It feels like this accurately captures the way we should be thinking about these APIs. What this API returns is not "the amount of concurrency available to the program" which is a property of the program, and thus even with just a single thread is effectively unbounded. But instead it returns "the amount of _parallelism_ available to the program", which is a resource hard-constrained by the machine's capacity (and can be further restricted by e.g. operating systems).

That's why I'd like to propose we rename this API from `available_concurrency` to `available_parallelism`. This still meets the criteria we previously established of not attempting to define what exactly we mean by "hardware", "threads", and other such words. Instead we only talk about "concurrency" as an abstract resource available to our program.

r? `@joshtriplett`

library/std/src/sys/hermit/thread.rs

@@ -97,7 +97,7 @@ impl Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     unsupported()
 }
 

library/std/src/sys/sgx/thread.rs

@@ -137,7 +137,7 @@ impl Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     unsupported()
 }
 

library/std/src/sys/unix/thread.rs

@@ -263,7 +263,7 @@ impl Drop for Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     cfg_if::cfg_if! {
         if #[cfg(any(
             target_os = "android",

library/std/src/sys/unsupported/thread.rs

@@ -31,7 +31,7 @@ impl Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     unsupported()
 }
 

library/std/src/sys/wasi/thread.rs

@@ -64,7 +64,7 @@ impl Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     unsupported()
 }
 

library/std/src/sys/wasm/atomics/thread.rs

@@ -40,7 +40,7 @@ impl Thread {
     pub fn join(self) {}
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     unsupported()
 }
 

library/std/src/sys/windows/thread.rs

@@ -100,7 +100,7 @@ impl Thread {
     }
 }
 
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
     let res = unsafe {
         let mut sysinfo: c::SYSTEM_INFO = crate::mem::zeroed();
         c::GetSystemInfo(&mut sysinfo);

library/std/src/thread/mod.rs

@@ -1453,12 +1453,14 @@ fn _assert_sync_and_send() {
 ///
 /// ```
 /// # #![allow(dead_code)]
-/// #![feature(available_concurrency)]
+/// #![feature(available_parallelism)]
 /// use std::thread;
 ///
-/// let count = thread::available_concurrency().map(|n| n.get()).unwrap_or(1);
+/// let count = thread::available_parallelism().map(|n| n.get()).unwrap_or(1);
 /// ```
-#[unstable(feature = "available_concurrency", issue = "74479")]
-pub fn available_concurrency() -> io::Result<NonZeroUsize> {
-    imp::available_concurrency()
+#[doc(alias = "hardware_concurrency")] // Alias for C++ `std::thread::hardware_concurrency`.
+#[doc(alias = "available_concurrency")] // Alias for a name we gave this API on unstable.
+#[unstable(feature = "available_parallelism", issue = "74479")]
+pub fn available_parallelism() -> io::Result<NonZeroUsize> {
+    imp::available_parallelism()
 }

library/test/src/helpers/concurrency.rs

@@ -9,6 +9,6 @@ pub fn get_concurrency() -> usize {
             _ => panic!("RUST_TEST_THREADS is `{}`, should be a positive integer.", value),
         }
     } else {
-        thread::available_concurrency().map(|n| n.get()).unwrap_or(1)
+        thread::available_parallelism().map(|n| n.get()).unwrap_or(1)
     }
 }

library/test/src/lib.rs

@@ -23,7 +23,7 @@
 #![feature(libc)]
 #![feature(rustc_private)]
 #![feature(nll)]
-#![feature(available_concurrency)]
+#![feature(available_parallelism)]
 #![feature(bench_black_box)]
 #![feature(internal_output_capture)]
 #![feature(panic_unwind)]

src/doc/rustc/src/tests/index.md

@@ -161,7 +161,7 @@ The following options affect how tests are executed.
 
 Sets the number of threads to use for running tests in parallel. By default,
 uses the amount of concurrency available on the hardware as indicated by
-[`available_concurrency`].
+[`available_parallelism`].
 
 This can also be specified with the `RUST_TEST_THREADS` environment variable.
 
@@ -265,7 +265,7 @@ Experimental support for using custom test harnesses is available on the
 
 [`--test` option]: ../command-line-arguments.md#option-test
 [`-Z panic-abort-tests`]: https://github.com/rust-lang/rust/issues/67650
-[`available_concurrency`]: ../../std/thread/fn.available_concurrency.html
+[`available_parallelism`]: ../../std/thread/fn.available_parallelism.html
 [`cargo test`]: ../../cargo/commands/cargo-test.html
 [`libtest`]: ../../test/index.html
 [`main` function]: ../../reference/crates-and-source-files.html#main-functions