wingo pushed a commit to branch wip-whippet
in repository guile.
commit ea15d142fcd6365170516a3799a23be5f695edca
Author: Andy Wingo <wi...@igalia.com>
AuthorDate: Mon Aug 5 15:19:07 2024 +0200
Update documentation
---
doc/collector-pcc.md | 11 ++++++-----
doc/collectors.md | 5 +++--
2 files changed, 9 insertions(+), 7 deletions(-)
diff --git a/doc/collector-pcc.md b/doc/collector-pcc.md
index c79fb2aea..f2f3ff390 100644
--- a/doc/collector-pcc.md
+++ b/doc/collector-pcc.md
@@ -24,11 +24,12 @@ entries to the worker's [shared
worklist](../src/shared-worklist.h).
When a worker runs out of local work, it will first try to remove work
from its own shared worklist, then will try to steal from other workers.
-Because threads compete to evacuate objects, `pcc` uses [atomic
-compare-and-swap instead of simple forwarding pointer
-updates](./manual.md#forwarding-objects), which imposes around a ~30%
-performance penalty. `pcc` generally starts to outperform `scc` when it
-can trace with 2 threads, and gets better with each additional thread.
+If only one tracing thread is enabled (`parallelism=1`), `pcc` uses
+non-atomic forwarding, but if multiple threads compete to evacuate
+objects, `pcc` uses [atomic compare-and-swap instead of simple
+forwarding pointer updates](./manual.md#forwarding-objects). This
+imposes around a ~30% performance penalty but having multiple tracing
+threads is generally worth it, unless the object graph is itself serial.
As with `scc`, the memory used for the external worklist is dynamically
allocated from the OS and is not currently counted as contributing to
diff --git a/doc/collectors.md b/doc/collectors.md
index c6fced97f..cdf4dcb8b 100644
--- a/doc/collectors.md
+++ b/doc/collectors.md
@@ -6,8 +6,7 @@ Whippet has five collectors currently:
- [Serial copying collector (`scc`)](./collector-scc.md): Like `semi`,
but with support for multiple mutator threads.
- [Parallel copying collector (`pcc`)](./collector-pcc.md): Like `scc`,
- but with support for multiple tracing threads. Faster than `scc` if
- multiple cores are available at collection-time.
+ but with support for multiple tracing threads.
- [Whippet collector (`whippet`)](./collector-whippet.md):
Immix-inspired collector. Optionally parallel, conservative (stack
and/or heap), and/or generational.
@@ -27,6 +26,8 @@ out mutator/embedder bugs. Then if memory is tight, switch to
If you are aiming for maximum simplicity and minimal code size (ten
kilobytes or so), use `semi`.
+Only use `scc` if you are investigating GC internals.
+
If you are writing a new project, you have a choice as to whether to pay
the development cost of precise roots or not. If you choose to not have
precise roots, then go for `stack-conservative-parallel-whippet`
