Docs about jobserver

NEWS.md

@@ -1,5 +1,9 @@
 # cargo-mutants changelog
 
+## Unreleased
+
+- New: cargo-mutants starts a GNU jobserver, shared across all children, so that running multiple `--jobs` does not spawn an excessive number of compiler processes. The jobserver is on by default and can be turned off with `--jobserver false`.
+
 ## 24.7.0
 
 - Fixed: The auto-set timeout for building mutants is now 2 times the baseline build time times the number of jobs, with a minimum of 20 seconds. This was changed because builds of mutants contend with each other for access to CPUs and may be slower than the baseline build.

book/src/SUMMARY.md

@@ -25,6 +25,7 @@
   - [Error values](error-values.md)
 - [Improving performance](performance.md)
   - [Parallelism](parallelism.md)
+  - [Jobserver](jobserver.md)
   - [Sharding](shards.md)
   - [Testing code changed in a diff](in-diff.md)
 - [Integrations](integrations.md)

book/src/jobserver.md

@@ -0,0 +1,12 @@
+# Jobserver
+
+The GNU Jobserver protocol enables a build system to limit the total number of concurrent jobs at any point in time.
+
+By default, cargo-mutants starts a jobserver configured to allow one job per CPU. This limit applies across all the subprocesses spawned by cargo-mutants, including all parallel jobs. This allows you to use `--jobs` to run multiple test suites in parallel, without causing excessive load on the system from running too many compiler tasks in parallel.
+
+`--jobserver=false` disables running the jobserver.
+
+`--jobserver-tasks=N` sets the number of tasks that the jobserver will allow to run concurrently.
+
+The Rust test framework does not currently use the jobserver protocol, so it won't affect tests, only builds. However, the jobserver can be observed by tests
+and build scripts in `CARGO_MAKEFLAGS`.