rust/src/doc
Manish Goregaokar b4615b5bf9
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`
2021-10-06 12:33:17 -07:00
..
book@eb1282ec44 Update books 2021-09-29 14:37:40 -07:00
edition-guide@2d9b1b9da7 Update cargo, books 2021-09-01 09:27:57 -07:00
embedded-book@4c76da9ddb Update books 2021-09-14 17:57:07 -07:00
man Rollup merge of #59685 - lzutao:patch-1, r=GuillaumeGomez 2019-04-04 15:09:07 +02:00
nomicon@2747c4bb2c Update books 2021-09-29 14:37:40 -07:00
reference@13747275bd Update books 2021-09-29 14:37:40 -07:00
rust-by-example@28aca4a369 Update books 2021-09-29 14:37:40 -07:00
rustc Rollup merge of #89324 - yoshuawuyts:hardware-parallelism, r=m-ou-se 2021-10-06 12:33:17 -07:00
rustc-dev-guide@d1f03cbaa3 Update books 2021-09-29 14:37:40 -07:00
rustdoc Fix typos in rustdoc/lints 2021-10-02 19:03:32 +02:00
unstable-book Support #[track_caller] on closures and generators 2021-09-22 15:19:33 -05:00
complement-design-faq.md Remove the FAQs in favor of the website 2015-12-23 14:03:45 -08:00
complement-lang-faq.md Remove the FAQs in favor of the website 2015-12-23 14:03:45 -08:00
complement-project-faq.md Remove the FAQs in favor of the website 2015-12-23 14:03:45 -08:00
favicon.inc Use https URLs to refer to rust-lang.org where appropriate. 2015-08-09 14:28:46 -07:00
footer.inc rustdoc: Improve playground run buttons 2016-10-15 18:32:03 +01:00
full-toc.inc
grammar.md Remove legacy grammar 2019-09-30 07:46:10 +02:00
guide-crates.md
guide-error-handling.md Convert old doc links to current edition 2019-02-13 14:39:25 +00:00
guide-ffi.md
guide-macros.md
guide-ownership.md Convert old doc links to current edition 2019-02-13 14:39:25 +00:00
guide-plugins.md Add top level sections to the Unstable Book. 2017-04-18 21:26:09 -04:00
guide-pointers.md Convert old doc links to current edition 2019-02-13 14:39:25 +00:00
guide-strings.md
guide-tasks.md
guide-testing.md Convert old doc links to current edition 2019-02-13 14:39:25 +00:00
guide-unsafe.md
guide.md
index.md Add link to rust website 2020-11-04 11:06:42 +01:00
intro.md
not_found.md dro -> duckduckgo 2018-10-05 08:52:44 -07:00
redirect.inc Exclude old book redirect stubs from search engines 2019-03-14 22:56:38 +00:00
reference.md Update reference.md 2021-07-10 19:51:36 +02:00
robots.txt Block version-specific docs from search engines 2020-03-14 02:29:35 +00:00
rust.css override rustdoc.css {webkit,moz} box-sizing:unset 2021-06-29 13:05:00 +08:00
rust.md Avoid linking to a moved page in rust.html 2017-03-29 15:38:47 +02:00
rustdoc.md
tutorial.md Update tutorial.md 2018-05-17 12:25:24 -07:00
version_info.html.template Add alt tags for logos 2016-01-20 11:53:20 -05:00