Rename std::thread::available_conccurrency to std::thread::available_parallelism

[yoshuawuyts]

Tracking issue: #74479

This PR renames std::thread::available_conccurrency to std::thread::available_parallelism.

Rationale

The API was initially named std::thread::hardware_concurrency, mirroring the C++ API of the same name. We eventually decided to omit any reference to the word "hardware" after this comment. 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), 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

[joshtriplett]

I don't have any objections to such a rename. Worth thinking about the cost of promoting the terminology distinction, given the divergence from the C++ name. I think people will understand what this does under either name. So the question is what will convey the concept most clearly taking into account both existing names and established terminology.

[camsteffen]

In the case of hyper-threading, the word "concurrency" seems more accurate - the CPU is not offering X amount of parallelism, but it is recommending X amount of concurrency.

[joshtriplett]

Thinking about it further, I think this change seems reasonable. In practice, I think "parallel" is actually the more likely name.

Would you consider also adding doc aliases for both hardware_concurrency (for C++ folks) and available_concurrency (for folks who search and find references to the previous name)?

[joshtriplett]

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[yoshuawuyts]

Would you consider also adding doc aliases for both hardware_concurrency (for C++ folks) and available_concurrency (for folks who search and find references to the previous name)?

Ah yeah, good call. Pushed!

[BurntSushi]

The new name SGTM.

The docs still contain a few mentions of the word "hardware." At the very least, we might want to update the opening line to be more consistent with the name of the routine.

I do think it would be nice to perhaps mention the word hardware or "CPU" in the docs somewhere. Something like, "this often corresponds to the number of logical CPUs available to the current program, but not always. For example, in scenarios Foo and Bar, ..." Basically, to give a bit more detail on what folks can realistically expect in terms of some common environments.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[yoshuawuyts]

I do think it would be nice to perhaps mention the word hardware or "CPU" in the docs somewhere.

I like that suggestion quite a bit! - If it's okay with y'all, once we merge this I'll submit a follow-up to this PR with docs changes.

[m-ou-se]

@bors r+

[bors]

📌 Commit 03fbc16 has been approved by m-ou-se

[bors]

🌲 The tree is currently closed for pull requests below priority 100. This pull request will be tested once the tree is reopened.

[Thomasdezeeuw]

A little side note for the overall process: it would really be nice if these kinds of changes, such as renaming, could be announced in the tracking issue. I know this pr links to the tracking issue, but GitHub doesn't send email for that. So for people like myself who mostly follow tracking issue using email I was in for a bit of a surprise that available_conccurrency was gone, not knowing it was renamed.

[yaahc]

A little side note for the overall process: it would really be nice if these kinds of changes, such as renaming, could be announced in the tracking issue. I know this pr links to the tracking issue, but GitHub doesn't send email for that. So for people like myself who mostly follow tracking issue using email I was in for a bit of a surprise that available_conccurrency was gone, not knowing it was renamed.

👍. I've gone ahead and nominated this suggestion for discussion during the next libs team meeting this Wednesday.