Remove the immix_stress_copying feature. Replace with separate options. (#1324)

`immix_stress_copying` may cause confusion with the stress GC and the
stress factor, as `immix_stress_copying` does not imply stress GCs. This
PR removes `immix_stress_copying`, and replaces with separate options to
control the specific behavior.

Author: qinsoon

Cargo.toml

@@ -157,8 +157,6 @@ immix_non_moving = []
 # if `immix_non_moving` is in use.
 sticky_immix_non_moving_nursery = []
 
-# Turn on stress copying for Immix. This is a debug feature to test copying for Immix plans.
-immix_stress_copying = []
 # Reduce block size for ImmixSpace.  This mitigates fragmentation when defrag is disabled.
 immix_smaller_block = []
 # Zero the unmarked lines after a GC cycle in immix. This helps debug untraced objects.

docs/userguide/src/SUMMARY.md

@@ -36,6 +36,7 @@
     - [Debugging Tips](portingguide/debugging/prefix.md)
         - [Enabling Debug Assertions](portingguide/debugging/assertions.md)
         - [Print Object Info](portingguide/debugging/print_obj_info.md)
+        - [Copying in Immix](portingguide/debugging/immix.md)
     - [Performance Tuning](portingguide/perf_tuning/prefix.md)
         - [Link Time Optimization](portingguide/perf_tuning/lto.md)
         - [Optimizing Allocation](portingguide/perf_tuning/alloc.md)

docs/userguide/src/migration/prefix.md

@@ -53,6 +53,25 @@ API changes:
         *   This means you can parse a string into `T` when setting an `MMTKOption<T>`.  For
             example, `options.plan.set(user_input.parse()?);`.
 
+### The feature `immix_stress_copying` is removed.
+
+```admonish tldr
+The feature `immix_stress_copying` is removed. Bindings can use MMTk options with the following values
+to achieve the same behavior as before: `immix_always_defrag=true,immix_defrag_every_block=true,immix_defrag_headroom_percent=50`
+```
+
+API changes:
+
+-   The feature `immix_stress_copying` is removed.
+-   module `util::options`
+    +   `Options` includes `immix_always_defrag`, which defaults to `false`.
+    +   `Options` includes `immix_defrag_every_block`, which defaults to `false`.
+    +   `Options` includes `immix_defrag_headroom_percent`, which defaults to `2`.
+
+See also:
+
+-   PR: <https://github.com/mmtk/mmtk-core/pull/1324>
+
 ## 0.30.0
 
 ### `live_bytes_in_last_gc` becomes a runtime option, and returns a map for live bytes in each space

docs/userguide/src/portingguide/debugging/immix.md

@@ -0,0 +1,37 @@
+# Debugging Copying in Immix Plans
+
+Immix uses opportunitic copying, which means it does not always copy objects.
+So a bug related with copying may be non-deterministic with Immix plans.
+
+One way to make copying more deterministic is to use the following
+[options](https://docs.mmtk.io/api/mmtk/util/options/struct.Options.html) to
+change the copying behavior of Immix.
+
+| Option                          | Default Value   | Note                                                                        |
+|---------------------------------|-----------------|-----------------------------------------------------------------------------|
+| `immix_always_defrag`           | `false`         | Immix only does defrag GC when necessary. Set to `true` to make every GC a defrag GC |
+| `immix_defrag_every_block`      | `false`         | Immix only defrags the most heavily fragmented blocks. Set to `true` to make Immix defrag every block with equal chances  |
+| `immix_defrag_headroom_percent` | `2`             | Immix uses 2% of the heap for defraging. We can reserve more headroom to copy more objects. 50% makes Immix behave like SemiSpace. |
+
+A common way to maximumally expose Immix copying bugs is to run with the following values:
+```rust
+// Set options with MMTkBuilder
+builder.options.immix_always_defrag.set(true);
+builder.options.immix_defrag_every_block.set(true);
+builder.options.immix_defrag_headroom_percent.set(50);
+```
+
+These options can also be used along with stress GC options:
+```rust
+// Do a stress GC for every 10MB allocation
+builder.options.stress_factor.set(10485760);
+```
+
+Options can also be set using environment variables.
+```console
+export MMTK_IMMIX_ALWAYS_DEFRAG=true
+export MMTK_IMMIX_DEFRAG_EVERY_BLOCK=true
+export MMTK_IMMIX_DEFRAG_HEADROOM_PERCENT=50
+export MMTK_STRESS_FACTOR=10485760
+```
+

src/policy/immix/defrag.rs

@@ -45,7 +45,6 @@ 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 = super::DEFRAG_HEADROOM_PERCENT;
 
     /// Allocate a new local histogram.
     pub const fn new_histogram(&self) -> Histogram {
@@ -73,12 +72,13 @@ impl Defrag {
         user_triggered: bool,
         exhausted_reusable_space: bool,
         full_heap_system_gc: bool,
+        stress_defrag: bool,
     ) {
         let in_defrag = defrag_enabled
             && (emergency_collection
                 || (collection_attempts > 1)
                 || !exhausted_reusable_space
-                || super::STRESS_DEFRAG
+                || stress_defrag
                 || (collect_whole_heap && user_triggered && full_heap_system_gc));
         info!("Defrag: {}", in_defrag);
         probe!(mmtk, immix_defrag, in_defrag);
@@ -88,7 +88,9 @@ impl Defrag {
 
     /// Get the number of defrag headroom pages.
     pub fn defrag_headroom_pages<VM: VMBinding>(&self, space: &ImmixSpace<VM>) -> usize {
-        space.get_page_resource().reserved_pages() * Self::DEFRAG_HEADROOM_PERCENT / 100
+        space.get_page_resource().reserved_pages()
+            * (*space.common().options.immix_defrag_headroom_percent)
+            / 100
     }
 
     /// Check if the defrag space is exhausted.

src/policy/immix/immixspace.rs

@@ -401,6 +401,7 @@ impl<VM: VMBinding> ImmixSpace<VM> {
             user_triggered_collection,
             self.reusable_blocks.len() == 0,
             full_heap_system_gc,
+            *self.common.options.immix_always_defrag,
         );
         self.defrag.in_defrag()
     }
@@ -912,7 +913,7 @@ impl<VM: VMBinding> PrepareBlockState<VM> {
 }
 
 impl<VM: VMBinding> GCWork<VM> for PrepareBlockState<VM> {
-    fn do_work(&mut self, _worker: &mut GCWorker<VM>, _mmtk: &'static MMTK<VM>) {
+    fn do_work(&mut self, _worker: &mut GCWorker<VM>, mmtk: &'static MMTK<VM>) {
         // Clear object mark table for this chunk
         self.reset_object_mark();
         // Iterate over all blocks in this chunk
@@ -926,7 +927,7 @@ impl<VM: VMBinding> GCWork<VM> for PrepareBlockState<VM> {
             let is_defrag_source = if !self.space.is_defrag_enabled() {
                 // Do not set any block as defrag source if defrag is disabled.
                 false
-            } else if super::DEFRAG_EVERY_BLOCK {
+            } else if *mmtk.options.immix_defrag_every_block {
                 // Set every block as defrag source if so desired.
                 true
             } else if let Some(defrag_threshold) = self.defrag_threshold {

src/policy/immix/mod.rs

@@ -14,35 +14,6 @@ pub const MAX_IMMIX_OBJECT_SIZE: usize = Block::BYTES >> 1;
 /// Mark/sweep memory for block-level only
 pub const BLOCK_ONLY: bool = false;
 
-// STRESS COPYING: Set the feature 'immix_stress_copying' 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 = cfg!(feature = "immix_stress_copying");
-
-/// Mark every allocated block as defragmentation source before GC. (for debugging)
-pub const DEFRAG_EVERY_BLOCK: bool = cfg!(feature = "immix_stress_copying");
-
-/// 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 = if cfg!(feature = "immix_stress_copying") {
-    50
-} else {
-    2
-};
-
 /// Mark lines when scanning objects.
 /// Otherwise, do it at mark time.
 pub const MARK_LINE_AT_SCAN_TIME: bool = true;

src/util/options.rs

@@ -901,7 +901,16 @@ options! {
     /// This only affects the memory for MMTk spaces.
     transparent_hugepages:  bool                    [|v: &bool| !v || cfg!(target_os = "linux")] = false,
     /// Count live bytes for objects in each space during a GC.
-    count_live_bytes_in_gc: bool                    [always_valid] = false
+    count_live_bytes_in_gc: bool                    [always_valid] = false,
+    /// Make every GC a defragment GC. (for debugging)
+    immix_always_defrag: bool                       [always_valid] = false,
+    /// Mark every allocated block as defragmentation source before GC. (for debugging)
+    /// Depending on the defrag headroom, Immix may not be able to defrag every block even if this option is set to true.
+    immix_defrag_every_block: bool                  [always_valid] = 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.
+    immix_defrag_headroom_percent: usize            [|v: &usize| *v <= 50] = 2
 }
 
 #[cfg(test)]