doc updates

Author: Tbkhi

src/parallel-rustc.md

@@ -1,30 +1,35 @@
 # Parallel Compilation
 
 As of <!-- date-check --> August 2022, the only stage of the compiler that is
-parallel is codegen. Some parts of the compiler have parallel implementations,
-such as query evaluation, type check and [monomorphization][monomorphization],
-but the general version of the compiler does not include parallelization
-functions. **To try out the current parallel compiler**, install `rustc` from
-source code with `parallel-compiler = true` in the `Config.toml`.
+parallel is [code generation stage][codegen] (codegen). Some parts of the
+compiler have parallel implementations, such as query evaluation, type check
+and [monomorphization][monomorphization], but the general version of the
+compiler does not include parallelization functions. **To try out the current
+parallel compiler**, install `rustc` from source code with `parallel-compiler =
+true` in the `Config.toml`.
 
 The lack of parallelism at other stages (for example, macro expansion) also 
 represents an opportunity for improving compiler performance.
 
 These next few sections describe where and how parallelism is currently used,
 and the current status of making parallel compilation the default in `rustc`.
 
+[codegen]: backend/codegen.md
+
 ## Code Generation
 
 During monomorphization the compiler splits up all the code to
 be generated into smaller chunks called _codegen units_. These are then generated by
 independent instances of LLVM running in parallel. At the end, the linker
 is run to combine all the codegen units together into one binary. This process
-occurs in the `rustc_codegen_ssa::base` module.
+occurs in the [`rustc_codegen_ssa::base`] module.
+
+[`rustc_codegen_ssa::base`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/base/index.html
 
 ## Data Structures
 
 The underlying thread-safe data-structures used in the parallel compiler
-can be found in the `rustc_data_structures::sync` module. These data structures 
+can be found in the [`rustc_data_structures::sync`] module. These data structures 
 are implemented differently depending on whether `parallel-compiler` is true.
 
 | data structure                   | parallel                                            | non-parallel |
@@ -54,24 +59,29 @@ are implemented differently depending on whether `parallel-compiler` is true.
 - On the other hand, we still need to figure out what other invariants 
   during compilation might not hold in parallel compilation.
 
-### WorkLocal
+[`rustc_data_structures::sync`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/sync/index.html
 
-`WorkLocal` is a special data structure implemented for parallel compilers. It
+### WorkerLocal
+
+[`WorkerLocal`] is a special data structure implemented for parallel compilers. It
 holds worker-locals values for each thread in a thread pool. You can only
 access the worker local value through the `Deref` `impl` on the thread pool it
 was constructed on. It panics otherwise. 
 
-`WorkLocal` is used to implement the `Arena` allocator in the parallel 
-environment, which is critical in parallel queries. Its implementation 
-is located in the `rustc-rayon-core::worker_local` module. However, in the 
-non-parallel compiler, it is implemented as `(OneThread<T>)`, whose `T` 
+`WorkerLocal` is used to implement the `Arena` allocator in the parallel
+environment, which is critical in parallel queries. Its implementation is
+located in the [`rustc_data_structures::sync::worker_local`] module. However,
+in the non-parallel compiler, it is implemented as `(OneThread<T>)`, whose `T`
 can be accessed directly through `Deref::deref`.
 
+[`rustc_data_structures::sync::worker_local`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/sync/worker_local/index.html
+[`WorkerLocal`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/sync/worker_local/struct.WorkerLocal.html
+
 ## Parallel Iterator
 
-The parallel iterators provided by the [`rayon`] crate are easy ways 
-to implement parallelism. In the current implementation of the parallel 
-compiler we use a custom [fork][rustc-rayon] of [`rayon`] to run tasks in parallel.
+The parallel iterators provided by the [`rayon`] crate are easy ways to
+implement parallelism. In the current implementation of the parallel compiler
+we use a custom [fork][rustc-rayon] of `rayon` to run tasks in parallel.
 
 Some iterator functions are implemented to run loops in parallel 
 when `parallel-compiler` is true.
@@ -87,10 +97,9 @@ when `parallel-compiler` is true.
 | **ModuleItems::par_impl_items**(&self, f: impl Fn(ImplItemId)) | run `f` on all impl items in the module                      | rustc_middle::hir          |
 | **ModuleItems::par_foreign_items**(&self, f: impl Fn(ForeignItemId)) | run `f` on all foreign items in the module                   | rustc_middle::hir          |
 
-There are a lot of loops in the compiler which can possibly be 
-parallelized using these functions. As of <!-- date-check--> August 
-2022, scenarios where the parallel iterator function has been used 
-are as follows:
+There are a lot of loops in the compiler which can possibly be parallelized
+using these functions. As of <!-- date-check--> August 2022, scenarios where
+the parallel iterator function has been used are as follows:
 
 | caller                                                  | scenario                                                     | callee                   |
 | ------------------------------------------------------- | ------------------------------------------------------------ | ------------------------ |
@@ -112,7 +121,7 @@ There are still many loops that have the potential to use parallel iterators.
 ## Query System
 
 The query model has some properties that make it actually feasible to evaluate
-multiple queries in parallel without too much of an effort:
+multiple queries in parallel without too much effort:
 
 - All data a query provider can access is via the query context, so
   the query context can take care of synchronizing access.
@@ -134,14 +143,15 @@ When a query `foo` is evaluated, the cache table for `foo` is locked.
   the compiler uses an extra thread *(named deadlock handler)* to detect, remove and 
   report the cycle error.
 
-Parallel query still has a lot of work to do, most of which is related to 
-the previous `Data Structures` and `Parallel Iterators`. See [this tracking issue][tracking].
+The parallel query feature still has implementation to do, most of which is
+related to the previous `Data Structures` and `Parallel Iterators`. See [this
+open feature tracking issue][tracking].
 
 ## Rustdoc
 
-As of <!-- date-check--> November 2022, there are still a number of steps
-to complete before `rustdoc` rendering can be made parallel (see a discussion of
-[parallel `rustdoc`][parallel-rustdoc]).
+As of <!-- date-check--> November 2022, there are still a number of steps to
+complete before `rustdoc` rendering can be made parallel (see a open discussion
+of [parallel `rustdoc`][parallel-rustdoc]).
 
 ## Resources