wingo pushed a commit to branch wip-whippet
in repository guile.
commit cc68a9a6107dc2767a1bd5a228cca1e222ceeb0f
Author: Andy Wingo <wi...@igalia.com>
AuthorDate: Mon Jan 13 21:42:18 2025 +0100
Update docs
---
README.md | 6 +++---
doc/collector-pcc.md | 7 +++++--
doc/collector-semi.md | 4 ++--
doc/collectors.md | 8 +++++---
doc/manual.md | 10 ++++++++--
5 files changed, 23 insertions(+), 12 deletions(-)
diff --git a/README.md b/README.md
index 466a5ea59..9ef9e3cc9 100644
--- a/README.md
+++ b/README.md
@@ -44,9 +44,9 @@ See the [documentation](./doc/README.md).
## Status and roadmap
-As of September 2024, Whippet is feature-complete! Of course there will
-surely be new features to build as Whippet gets integrated it into
-language run-times, but the basics are there.
+As of January 2025, Whippet is good to go! Of course there will surely
+be new features to build as Whippet gets integrated it into language
+run-times, but the basics are there.
The next phase on the roadmap is support for tracing, and
some performance noodling.
diff --git a/doc/collector-pcc.md b/doc/collector-pcc.md
index ef8085ed7..dc7bd1fb0 100644
--- a/doc/collector-pcc.md
+++ b/doc/collector-pcc.md
@@ -20,8 +20,11 @@ the same performance characteristics with a single mutator
and with
parallelism disabled, additionally allowing multiple mutators, and
scaling better with multiple tracing threads.
-Also like `semi`, `pcc` is not generational yet. If and when `pcc`
-grows a young generation, it would be a great collector.
+`pcc` has a generational configuration, conventionally referred to as
+`generational-pcc`, in which both the nursery and the old generation are
+copy spaces. Objects stay in the nursery for one cycle before moving on
+to the old generation. This configuration is a bit new (January 2025)
+and still needs some tuning.
## Implementation notes
diff --git a/doc/collector-semi.md b/doc/collector-semi.md
index 1900d2d27..ea84720df 100644
--- a/doc/collector-semi.md
+++ b/doc/collector-semi.md
@@ -19,5 +19,5 @@ size, and performs best with ample heap sizes; between 3× and
5× is
best.
The semi-space collector doesn't support multiple mutator threads. If
-you want a whole-heap copying collector for a multi-threaded mutator,
-look at [pcc](./collector-pcc.md).
+you want a copying collector for a multi-threaded mutator, look at
+[pcc](./collector-pcc.md).
diff --git a/doc/collectors.md b/doc/collectors.md
index 6e21fcd77..90f4867fc 100644
--- a/doc/collectors.md
+++ b/doc/collectors.md
@@ -3,8 +3,9 @@
Whippet has four collectors currently:
- [Semi-space collector (`semi`)](./collector-semi.md): For
single-threaded embedders who are not too tight on memory.
- - [Parallel copying collector (`pcc`)](./collector-pcc.md): Like `semi`,
- but with support for multiple mutator and tracing threads.
+ - [Parallel copying collector (`pcc`)](./collector-pcc.md): Like
+ `semi`, but with support for multiple mutator and tracing threads and
+ generational collection.
- [Mostly marking collector (`mmc`)](./collector-mmc.md):
Immix-inspired collector. Optionally parallel, conservative (stack
and/or heap), and/or generational.
@@ -30,8 +31,9 @@ precise roots, then go for `stack-conservative-parallel-mmc`
directly.
## More collectors
-It would be nice to have a classic generational GC, perhaps using
+It would be nice to have a generational GC that uses the space from
`parallel-mmc` for the old generation but a pcc-style copying nursery.
+We have `generational-pcc` now, so this should be possible.
Support for concurrent marking in `mmc` would be good as well, perhaps
with a SATB barrier. (Or, if you are the sort of person to bet on
diff --git a/doc/manual.md b/doc/manual.md
index c299128bf..1ddfcb556 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -112,8 +112,8 @@ If the `gc_atomic_forward`'s state is `BUSY`, the collector
will call
`gc_atomic_forward_retry_busy`; a return value of 0 means the object is
still busy, because another thread is attempting to forward it.
Otherwise the forwarding state becomes either `FORWARDED`, if the other
-thread succeeded in forwarding it, or `ABORTED`, indicating that the
-other thread failed to forward it.
+thread succeeded in forwarding it, or go back to `NOT_FORWARDED`,
+indicating that the other thread failed to forward it.
If the forwarding state is `FORWARDED`, the collector will call
`gc_atomic_forward_address` to get the new address.
@@ -351,6 +351,12 @@ $(COMPILE) -DGC_PARALLEL=1 -DGC_PRECISE_ROOTS=1 \
-include foo-embedder.h -o gc.o -c pcc.c
```
+You can also build `pcc` in a generational configuration by passing
+`-DGC_GENERATIONAL=1`. The nursery is 2 MB per active mutator, capped
+to the number of processors, so if the last cycle had a maximum of 4
+mutator threads active at the same time and your machine has 24 cores,
+your nursery would be 8 MB.
+
#### Building `mmc`
Finally, there is the mostly-marking collector. It can collect roots
