Improve parallel join chapter in the book.
As mentioned in the chapter dedicated on how to [dispatch][c3] systems,
Specs automatically parallelizes system execution when there are non-conflicting
-system data requirements (every system data may only be accessed
-mutably once xor immutably from multiple systems).
+system data requirements (each resource in the system data may only be accessed either
+once mutably or many times immutably from multiple systems).
[c3]: ./03_dispatcher.html
+## Basic parallization
+
What isn't automatically parallelized by Specs are
the joins made within a single system:
@@ -25,7 +27,7 @@ This means that, if there are hundreds of thousands of entities and only few
systems that actually can be executed in parallel, then the full power
of CPU cores cannot be fully utilized.
-To fix this inefficiency and to parallelize the joining, the `join`
+To fix this potential inefficiency and to parallelize the joining, the `join`
method call can be exchanged for `par_join`:
```rust,ignore
@@ -45,8 +47,10 @@ fn run(&mut self, (vel, mut pos): Self::SystemData) {
}
```
-The `par_join` method produces a type implementing [`rayon`s `ParallelIterator`][ra]
+There is always overhead in parallelization, so you should always carefully profile to see if there are benefits in the switch. If you have only few things to iterate over then sequential join is faster.
+
+The `par_join` method produces a type implementing rayon's [`ParallelIterator`][ra]
trait which provides lots of helper methods to manipulate the iteration,
the same way as the normal `Iterator` trait does.
-[ra]: https://docs.rs/rayon/0.9.0/rayon/iter/trait.ParallelIterator.html
+[ra]: https://docs.rs/rayon/1.0.0/rayon/iter/trait.ParallelIterator.html
