From 2ba847967eebf95800716fe7c03d780b5130a8f8 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Mon, 20 Dec 2021 10:48:30 -0800 Subject: [PATCH] README.md: Clarify multiple versions. --- README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 77ebbae..6f24ffb 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,20 @@ This program plots the Mandelbrot set and writes it out as a PNG file. It uses Rust's concurrency primitives to distribute the work across eight threads. -Different commits show different implementation strategies: +The book shows several different versions of this program: single- and multi-threaded versions in the "Tour of Rust" chapter, and a final version based on the Rayon crate in the "Concurrency" chapter, which makes more effective use of parallelism. + +Each of these versions appears on a different branch in this repository: * [Branch `single-threaded`](https://github.com/ProgrammingRust/mandelbrot/tree/single-threaded) is the base version of the program. It does all the work on the main - thread. + thread. This is the first version shown in the "Tour of Rust" chapter. * [Branch `bands`](https://github.com/ProgrammingRust/mandelbrot/tree/bands) - splits the plotting area up into eight bands, and assigns one thread - to each. This often makes poor use of the threads, because some - bands take significantly longer than others to complete: once a fast - thread completes its band, its CPU goes idle while its less - fortunate brethren are still hard at work. + splits the plotting area up into eight bands, and assigns one thread to + each. This often makes poor use of the threads, because some bands take + significantly longer than others to complete: once a fast thread completes + its band, its CPU goes idle while its less fortunate brethren are still hard + at work. This is the final version shown in the Tour. * [Branch `task-queue`](https://github.com/ProgrammingRust/mandelbrot/tree/task-queue) gets an almost perfect linear speedup from its threads. It splits @@ -21,7 +23,7 @@ Different commits show different implementation strategies: bands from a common pool until the pool is empty. When a thread finishes one band, it goes back for more work. Since the bands still take different amounts of time to render, the problem cited above - still occurs, but on a much smaller scale. + still occurs, but on a much smaller scale. This version is not shown in the book. * [Branch `lockfree`](https://github.com/ProgrammingRust/mandelbrot/tree/lockfree) uses Rust's atomic types to implement a lock-free iterator type, and @@ -29,12 +31,13 @@ Different commits show different implementation strategies: mutex-protected count. On Linux, this is no faster than the mutex-based version, which isn't too surprising: on Linux, locking and unlocking an uncontended mutex *is* simply a pair of atomic - operations. + operations. This version is also not shown in the book. * [Branch `rayon`](https://github.com/ProgrammingRust/mandelbrot/tree/rayon) - uses the Rayon library instead of Crossbeam. Rayon provides a - *parallel iterator* API that makes our code much simpler. It looks - a lot like Rust code that uses plain old iterators. + uses the Rayon library instead of Crossbeam. Rayon provides a *parallel + iterator* API that makes our code much simpler. It looks a lot like Rust + code that uses plain old iterators. This is the final version shown in the + Concurrency chapter. ## License