Address review comments.

Author: nnethercote

posts/inside-rust/2023-11-10-parallel-rustc.md

@@ -7,7 +7,8 @@ team: The Parallel Rustc Working Group <https://www.rust-lang.org/governance/tea
 
 The Rust compiler's front-end can now use parallel execution to significantly
 reduce compile times. To try it out, run the nightly compiler with the `-Z
-threads=8` command line option.
+threads=8` command line option. This feature is currently experimental, and we
+aim to ship it in the stable compiler some time in 2024.
 
 Keep reading to learn why a parallel front-end is needed and how it works, or
 just skip ahead to the [How to use it](parallel-rustc.html#how-to-use-it)
@@ -136,14 +137,14 @@ Again, there are several things worth nothing.
 
 ### Putting it all together
 
-Rust compilation has long benefited from intraprocess parallelism, via Cargo,
-and from interprocess parallelism in the back-end. It can now also benefit from
-interprocess parallelism in the front-end.
+Rust compilation has long benefited from interprocess parallelism, via Cargo,
+and from intraprocess parallelism in the back-end. It can now also benefit from
+intraprocess parallelism in the front-end.
 
-Attentive readers might be wondering how intraprocess parallelism and
-interprocess parallelism interact. If we have 20 parallel rustc invocations and
-each one can have up to 16 threads running, might we end up 100s of threads on
-a machine with only 10s of cores, resulting in inefficient execution as the OS
+Attentive readers might wonder how interprocess parallelism and intraprocess
+parallelism interact. If we have 20 parallel rustc invocations and each one can
+have up to 16 threads running, could we end up with hundreds of threads on a
+machine with only tens of cores, resulting in inefficient execution as the OS
 tries its best to schedule them?
 
 Fortunately no. The compiler uses the [jobserver
@@ -157,33 +158,44 @@ the number of threads will not exceed the number of cores.
 As of (XXX: date enabled) the nightly compiler is [shipped with the parallel
 front-end enabled](https://github.com/rust-lang/rust/pull/117435). However,
 **by default it runs in single-threaded mode** and won't reduce compile times.
-Keen users who want to try multi-threaded mode should use the `-Z threads=8`
-option.
-
-This default may be surprising. Why parallelize the front-end and then run it
-in single-threaded mode? The answer is simple: caution. This is a big change!
-The parallel front-end has a lot of new code. Single-threaded mode exercises
-most of the new code, but excludes the possibility of threading bugs such as
-deadlocks that still occasionally affect multi-threaded mode. Parallel
-execution is harder to get right than serial execution, even in Rust. For this
-reason the parallel front-end also won't be shipped in Beta or Stable releases
-for some time.
+
+Keen users can opt into multi-threaded mode with the `-Z threads` option. For
+example:
+```
+$ RUSTFLAGS="-Z threads=8" cargo build --release
+```
+Alternatively, to request these instructions from a
+[config.toml](https://doc.rust-lang.org/cargo/reference/config.html) file (for
+one or more projects), add these lines:
+```
+[build]
+rustflags = ["-Z", "threads=8"]
+```
+It may be surprising that single-thread mode is the default. Why parallelize
+the front-end and then run it in single-threaded mode? The answer is simple:
+caution. This is a big change! The parallel front-end has a lot of new code.
+Single-threaded mode exercises most of the new code, but excludes the
+possibility of threading bugs such as deadlocks that still occasionally affect
+multi-threaded mode. Parallel execution is harder to get right than serial
+execution, even in Rust. For this reason the parallel front-end also won't be
+shipped in Beta or Stable releases for some time.
 
 ### Performance effects
 
 When the parallel front-end is run in single-threaded mode, compilation times
-are typically within 2% of the serial front-end, which should be barely
-noticeable.
+are typically 0% to 2% slower than with the serial front-end. This should be
+barely noticeable.
 
 When the parallel front-end is run in multi-threaded mode with `-Z threads=8`,
-out [measurements on real-world
-code](https://github.com/rust-lang/compiler-team/issues/681) on show that
-compile times can be reduced by up to 50%, though the affects vary widely and
-depend greatly on the characteristics of the code being compiled and the build
+our [measurements on real-world
+code](https://github.com/rust-lang/compiler-team/issues/681) show that compile
+times can be reduced by up to 50%, though the affects vary widely and depend
+greatly on the characteristics of the code being compiled and the build
 configuration. For example, dev builds are likely to see bigger improvements
 than release builds because release builds usually spend more time doing
 optimizations in the back-end. A small number of cases compile more slowly in
-multi-threaded mode than single-threaded mode.
+multi-threaded mode than single-threaded mode. These are mostly tiny programs
+that already compile quickly.
 
 We recommend eight threads because this is the configuration we have tested the
 most and it is known to give good results. Values lower than eight will see