Move constants and add comments for stress copying (#1008)

Move the constant `DEFRAG_HEADROOM_PERCENT` to `crate::policy::immix` so
that all constants needed to be modified to stress copying are adjacent.

Add a comment about how to change those constants and the reasons
behind.

src/policy/immix/defrag.rs

@@ -45,7 +45,7 @@ impl Defrag {
     const NUM_BINS: usize = (Block::LINES >> 1) + 1;
     const DEFRAG_LINE_REUSE_RATIO: f32 = 0.99;
     const MIN_SPILL_THRESHOLD: usize = 2;
-    const DEFRAG_HEADROOM_PERCENT: usize = 2;
+    const DEFRAG_HEADROOM_PERCENT: usize = super::DEFRAG_HEADROOM_PERCENT;
 
     /// Allocate a new local histogram.
     pub const fn new_histogram(&self) -> Histogram {

src/policy/immix/mod.rs

@@ -17,13 +17,31 @@ pub const BLOCK_ONLY: bool = false;
 /// Do we allow Immix to do defragmentation?
 pub const DEFRAG: bool = !cfg!(feature = "immix_non_moving"); // defrag if we are allowed to move.
 
+// STRESS COPYING: Set the following options so that Immix will copy as many objects as possible.
+// Useful for debugging copying GC if you cannot use SemiSpace.
+//
+// | constant                  | when    | value   | comment                                                              |
+// |---------------------------|---------|---------|----------------------------------------------------------------------|
+// | `STRESS_DEFRAG`           | default | `false` | By default, Immix only does defrag GC when necessary.                |
+// | `STRESS_DEFRAG`           | stress  | `true`  | Set to `true` to force every GC to be defrag GC.                     |
+// |                           |         |         |                                                                      |
+// | `DEFRAG_EVERY_BLOCK`      | default | `false` | By default, Immix only defrags the most heavily fragmented blocks.   |
+// | `DEFRAG_EVERY_BLOCK`      | stress  | `true`  | Set to `true` to make every block a defrag source.                   |
+// |                           |         |         |                                                                      |
+// | `DEFRAG_HEADROOM_PERCENT` | default | `2`     | Immix stops copying when space exhausted.                            |
+// | `DEFRAG_HEADROOM_PERCENT` | stress  | `50`    | Reserve enough headroom to copy all objects.  50% is like SemiSpace. |
+
 /// Make every GC a defragment GC. (for debugging)
 pub const STRESS_DEFRAG: bool = false;
 
 /// Mark every allocated block as defragmentation source before GC. (for debugging)
-/// Set both this and `STRESS_DEFRAG` to true to make Immix move as many objects as possible.
 pub const DEFRAG_EVERY_BLOCK: bool = false;
 
+/// Percentage of heap size reserved for defragmentation.
+/// According to [this paper](https://doi.org/10.1145/1375581.1375586), Immix works well with
+/// headroom between 1% to 3% of the heap size.
+pub const DEFRAG_HEADROOM_PERCENT: usize = 2;
+
 /// If Immix is used as a nursery space, do we prefer copy?
 pub const PREFER_COPY_ON_NURSERY_GC: bool =
     !cfg!(feature = "immix_non_moving") && !cfg!(feature = "sticky_immix_non_moving_nursery"); // copy nursery objects if we are allowed to move.