perf(gc): scope the shape-table and box-roots minor scanners to young entries; per-minor pause_us

cc-perf-campaign/codex/REPORT_minor_scanner_young_logs.md

@@ -0,0 +1,107 @@
+# Minor scanner young logs
+
+Implementation SHA: `d399c39ddb638a92b2735a6bacc2aef13def944a`
+
+## Map and mechanism
+
+- `object/shapes.rs:1972` scans two address-keyed structures. `families` maps a
+  keys-array address to every descriptor id whose slab record carries that
+  address; the descriptor record is the authoritative rewritable `keys` edge.
+  A family is a strong minor root only when an old receiver or an optimization
+  cache carries one of its descriptors. `indices` is a weak key-to-slot
+  accelerator keyed by the same keys-array address and needs only relocation
+  repair. Shape property-key payloads are strings/symbol headers, both GC
+  leaves. Nursery keys arrays can move; old arrays cannot; Longlived arrays do
+  not move or die but can temporarily contain a collectible key leaf.
+- Shapes already had #9755's `young_keys` address log and the four
+  `shapes.indices` arm sites. Its keep predicate was
+  `addr_is_minor_relevant`, so every Longlived keys array stayed in the log
+  forever. `object/shapes.rs:2154` now re-derives actual minor work: nursery
+  addresses remain for relocation, malloc roots remain while carrier-owned,
+  and a Longlived carrier remains only while its property-key payload contains
+  a collectible leaf. `object/shapes.rs:271` receives old/cache carrier notes
+  without recursively borrowing the shape table; `object/shapes.rs:801` is the
+  enforced structural-publication funnel that re-arms a same-address mutation.
+  Scanner-internal rekeys do not enqueue a duplicate visit.
+- `box.rs:954` previously walked every address in `BOX_REGISTRY`. These are
+  malloc-allocated mutable-capture/async state cells; the registry address is
+  not a GC pointer. Only the `Box::value` NaN-box can point into the nursery.
+  `I32Box` and `BoolBox` registries contain no GC edge and were never part of
+  this scanner. There was no partial box log.
+- `box.rs:123` adds the box remembered set. Both allocation arms and both
+  mutation ABIs arm it before publishing a minor-relevant payload
+  (`box.rs:133`, `box.rs:705`, `box.rs:725`, `box.rs:1318`, `box.rs:1357`).
+  The trusted setter is included because generated boxed-local stores use it;
+  omitting that silent path would violate the enforced-funnel rule. Release
+  paths only clear/de-register cells, and scanner rewrites compact their own
+  entries. `box.rs:1040` owns the priced `visited` counter.
+- Both minor walks sort/deduplicate their logged addresses, drop stale keys,
+  and keep only post-visit non-old entries. Full/major scans still enumerate
+  the authoritative whole tables and rebuild the logs. Under
+  `debug_assertions` and in lib tests, each minor scan re-derives the relevant
+  set from the whole table and asserts that the log is complete.
+- `gc/copying.rs:1889` now emits `pause_us=` and `scan_us=` together on every
+  completed `[gc-copy-minor] ran` line. `pause_us` is sampled as the final
+  action before the copied-minor returns to the mutator; `scan_us` is the
+  already-profiled scanner total returned by `gc/scanner_profile.rs:131`.
+  Timing remains behind the existing cached `PERRY_GC_DIAG` gate.
+
+## Tests and sabotages
+
+- `shape_table_minor_walk_visits_exactly_k_young_entries`: N old families and
+  k young families produce `visited == k`. Sabotage: remove
+  `note_young_keys`; the completeness re-derivation panics.
+- `shape_table_rederivation_rejects_a_suppressed_logging_site`: a test-only
+  suppression skips the production family arm and the scan must panic.
+- `shape_mutation_to_new_young_key_rearms_minor_log`: a Longlived carrier that
+  gains a new nursery key at the same address must move that key. Sabotage:
+  remove the re-arm in `stamp_object_shape_id_with_carrier_note`.
+- `box_roots_minor_walk_visits_exactly_k_young_entries`: N old payloads and k
+  young payloads produce `visited == k`. Sabotage: remove either allocator arm.
+- `box_root_rederivation_rejects_a_suppressed_mutation_hook`: a test-only
+  suppression skips `js_box_set_bits` logging and the authoritative registry
+  walk must panic.
+- `box_mutation_to_new_young_object_is_visited`: an old box changed to a new
+  nursery object is visited. Sabotage: remove the setter hook.
+- `promoted_shape_entry_leaves_young_log_and_remains_in_major_walk` and
+  `promoted_box_root_leaves_log_and_is_found_by_full_walk`: promotion makes
+  `kept == 0`, while the next authoritative full walk still visits the entry.
+  Sabotage: retain the pre-visit/from-space classification or scope the full
+  walk to the log.
+- Existing scanner-completeness and moving-witness suites are unchanged and
+  remain part of the requested runtime-lib gate.
+
+## Validation
+
+- `scripts/check_file_size.sh`: PASS.
+- `git diff --check`: PASS.
+- Cargo gates: NOT RUN. `df -g /` immediately before the first possible Cargo
+  invocation reported `0` GB available, below the binding 12 GB floor. Per the
+  task rule, no Cargo command was started and no wait for disk was attempted.
+- Not run for the same reason:
+  `cargo test -p perry-runtime --release --lib -- --test-threads=1`;
+  `cargo build --release -p perry-runtime --features wasm-host`;
+  `cargo build --release -p perry`.
+
+## Predictions and exact perrymaster request
+
+Predictions: on a zero-live steady minor,
+`object::shapes::scan_shape_table_rekey_mut` and
+`r#box::scan_box_roots_mut` each fall from about 2 ms to at most 0.2 ms;
+steady-minor scanner total falls from 7–8 ms to at most 3 ms; every completed
+minor reports `pause_us` and `scan_us`. CPU bound is about -3% at 3300 chars
+and larger at 400 chars, where minors are a larger share. RSS should be
+unchanged (small retained log capacities only, within the allowed 1–10%).
+
+Perrymaster request, from pushed SHA: relink on the I7-view tree
+(runtime-only), then run the three gates through
+`/Users/amlug/projects/perry/secret-tests/cc-perf-campaign/measure_lock.sh --build`
+at `-j4` using detached `nohup`: (1)
+`cargo test -p perry-runtime --release --lib -- --test-threads=1`, (2)
+`cargo build --release -p perry-runtime --features wasm-host`, and (3)
+`cargo build --release -p perry`. Because this is GC-adjacent, the coordinator
+must apply `run-extended-tests`. After green gates, do one graceful four-turn
+3300-char run and one 400-char run with `PERRY_GC_DIAG=1`, preserving complete
+`[gc-copy-minor] ran pause_us=... scan_us=...` and
+`[gc-scanner-profile] copying_minor` lines. Then run paired 5x3300 + 3x400
+against I7-view for CPU and RSS.

changelog.d/minor-scanner-young-logs.md

@@ -0,0 +1,5 @@
+Copying-minor scans of shape descriptors and captured-variable boxes now walk
+only entries that can still expose non-old GC pointers. This removes the two
+largest table-size-dependent root-scan costs, while full collections retain
+their authoritative whole-table walks. `PERRY_GC_DIAG=1` also reports the
+whole copying-minor pause and its scanner share on each completed-minor line.

crates/perry-runtime/src/box.rs

@@ -117,6 +117,28 @@ crate::perry_thread_local! {
             16 * 1024,
             crate::fast_hash::PtrHasher,
         ));
+    /// Box addresses whose JSValue payload may matter to a minor collection.
+    /// The registry itself is the authoritative full/major root set; this is
+    /// only its minor remembered set.
+    static BOX_YOUNG_ROOTS: std::cell::RefCell<crate::gc::young_log::YoungLog<usize>> =
+        const { std::cell::RefCell::new(crate::gc::young_log::YoungLog::new()) };
+    #[cfg(test)]
+    static BOX_YOUNG_LOG_SUPPRESSED: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+const BOX_YOUNG_LOG_NAME: &str = "box.roots";
+
+/// Arm the box minor-root log before publishing a young payload.
+#[inline]
+fn note_box_young_root(addr: usize, bits: u64) {
+    if !crate::gc::young_log::bits_are_minor_relevant(bits) {
+        return;
+    }
+    #[cfg(test)]
+    if BOX_YOUNG_LOG_SUPPRESSED.with(std::cell::Cell::get) {
+        return;
+    }
+    BOX_YOUNG_ROOTS.with(|log| log.borrow_mut().note(addr));
 }
 
 /// Number of slots in each registry's direct-mapped positive cache. Eight
@@ -680,6 +702,7 @@ pub extern "C" fn js_box_alloc_bits(initial_bits: i64) -> *mut Box {
         unsafe {
             (*ptr).value = initial_bits as u64;
         }
+        note_box_young_root(addr, initial_bits as u64);
         BOX_REGISTRY.with(|r| {
             r.borrow_mut().insert(addr);
         });
@@ -699,6 +722,7 @@ pub extern "C" fn js_box_alloc_bits(initial_bits: i64) -> *mut Box {
             return std::ptr::null_mut();
         }
         (*ptr).value = initial_bits as u64;
+        note_box_young_root(ptr as usize, initial_bits as u64);
         BOX_REGISTRY.with(|r| {
             r.borrow_mut().insert(ptr as usize);
         });
@@ -928,7 +952,14 @@ pub fn scan_box_roots(mark: &mut dyn FnMut(f64)) {
 }
 
 pub fn scan_box_roots_mut(visitor: &mut crate::gc::RuntimeRootVisitor<'_>) {
+    if visitor.young_scope() {
+        scan_box_young_roots_mut(visitor);
+        return;
+    }
     let full_trace = crate::gc::full_trace_active();
+    let mut visited = 0u64;
+    let table_len = BOX_REGISTRY.with(|registry| registry.borrow().len()) as u64;
+    let mut kept = Vec::new();
     ASYNC_PENDING_RELEASES.with(|pending| {
         let pending = pending.borrow();
         BOX_REGISTRY.with(|r| {
@@ -957,11 +988,103 @@ pub fn scan_box_roots_mut(visitor: &mut crate::gc::RuntimeRootVisitor<'_>) {
                 if addr >= 0x1000 && (addr as u64) < 0x0001_0000_0000_0000 && addr % 8 == 0 {
                     unsafe {
                         visitor.visit_nanbox_u64_raw_slot(&raw mut (*ptr).value);
+                        if crate::gc::young_log::bits_are_minor_relevant((*ptr).value) {
+                            kept.push(addr);
+                        }
                     }
+                    visited += 1;
                 }
             }
         });
     });
+    let kept_len = kept.len() as u64;
+    BOX_YOUNG_ROOTS.with(|log| {
+        let mut log = log.borrow_mut();
+        let _ = log.take_sorted();
+        log.extend(kept);
+    });
+    crate::gc::young_log::note_walk(
+        BOX_YOUNG_LOG_NAME,
+        crate::gc::young_log::YoungLogWalk {
+            partial: false,
+            logged: visited,
+            visited,
+            kept: kept_len,
+            table_len,
+        },
+    );
+}
+
+/// Every live box whose current payload a minor can move, mark through, or
+/// sweep. This is the authoritative debug re-derivation of the remembered set.
+fn relevant_box_roots() -> Vec<usize> {
+    let mut relevant = BOX_REGISTRY.with(|registry| {
+        registry
+            .borrow()
+            .iter()
+            .copied()
+            .filter(|&addr| {
+                let ptr = addr as *mut Box;
+                is_plausible_box_ptr(ptr)
+                    && unsafe { crate::gc::young_log::bits_are_minor_relevant((*ptr).value) }
+            })
+            .collect::<Vec<_>>()
+    });
+    relevant.sort_unstable();
+    relevant
+}
+
+/// Minor root scan: price only the logged boxes, and compact the log from the
+/// post-visit payloads. The visit counter lives here because this is the work
+/// whose fixed cost the counter measures.
+fn scan_box_young_roots_mut(visitor: &mut crate::gc::RuntimeRootVisitor<'_>) {
+    let table_len = BOX_REGISTRY.with(|registry| registry.borrow().len()) as u64;
+    #[cfg(any(debug_assertions, test))]
+    BOX_YOUNG_ROOTS.with(|log| {
+        let relevant = relevant_box_roots();
+        log.borrow()
+            .debug_assert_logged(BOX_YOUNG_LOG_NAME, &relevant);
+    });
+
+    let mut logged = 0u64;
+    let mut visited = 0u64;
+    let mut kept = BOX_YOUNG_ROOTS.with(|log| log.borrow_mut().take_spare());
+    loop {
+        let batch = BOX_YOUNG_ROOTS.with(|log| log.borrow_mut().take_sorted());
+        if batch.is_empty() {
+            break;
+        }
+        logged += batch.len() as u64;
+        for addr in batch {
+            let registered = BOX_REGISTRY.with(|registry| registry.borrow().contains(&addr));
+            if !registered {
+                continue;
+            }
+            let ptr = addr as *mut Box;
+            if !is_plausible_box_ptr(ptr) {
+                continue;
+            }
+            visited += 1;
+            unsafe {
+                visitor.visit_nanbox_u64_raw_slot(&raw mut (*ptr).value);
+                if crate::gc::young_log::bits_are_minor_relevant((*ptr).value) {
+                    kept.push(addr);
+                }
+            }
+        }
+    }
+    let kept_len = kept.len() as u64;
+    BOX_YOUNG_ROOTS.with(|log| log.borrow_mut().extend(kept));
+    crate::gc::young_log::note_walk(
+        BOX_YOUNG_LOG_NAME,
+        crate::gc::young_log::YoungLogWalk {
+            partial: true,
+            logged,
+            visited,
+            kept: kept_len,
+            table_len,
+        },
+    );
 }
 
 /// Get the raw JSValue bit pattern from a box.
@@ -1213,6 +1336,7 @@ pub extern "C" fn js_box_set_bits(ptr: *mut Box, value_bits: i64) {
             return;
         }
         let bits = value_bits as u64;
+        note_box_young_root(ptr as usize, bits);
         (*ptr).value = bits;
         crate::gc::runtime_write_barrier_root_nanbox(bits);
     }
@@ -1232,6 +1356,7 @@ pub extern "C" fn js_box_set_bits(ptr: *mut Box, value_bits: i64) {
 #[no_mangle]
 pub unsafe extern "C" fn js_box_set_bits_trusted_no_barrier(ptr: *mut Box, value_bits: i64) {
     unsafe {
+        note_box_young_root(ptr as usize, value_bits as u64);
         (*ptr).value = value_bits as u64;
     }
 }
@@ -1479,6 +1604,7 @@ pub(crate) fn test_clear_box_registry() {
     BOX_REGISTRY.with(|r| r.borrow_mut().clear());
     I32_BOX_REGISTRY.with(|r| r.borrow_mut().clear());
     BOOL_BOX_REGISTRY.with(|r| r.borrow_mut().clear());
+    BOX_YOUNG_ROOTS.with(|log| log.borrow_mut().clear());
     BOX_FREE_HEAD.with(|h| h.set(0));
     I32_BOX_FREE_HEAD.with(|h| h.set(0));
     BOOL_BOX_FREE_HEAD.with(|h| h.set(0));
@@ -1501,6 +1627,25 @@ pub(crate) fn test_clear_box_registry() {
     }
 }
 
+/// Test-only sabotage of the box write-side arming hook. The production
+/// scanner's re-derivation must reject the missing log entry.
+#[cfg(test)]
+pub(crate) struct TestBoxYoungLogSuppression(bool);
+
+#[cfg(test)]
+impl TestBoxYoungLogSuppression {
+    pub(crate) fn new() -> Self {
+        Self(BOX_YOUNG_LOG_SUPPRESSED.with(|cell| cell.replace(true)))
+    }
+}
+
+#[cfg(test)]
+impl Drop for TestBoxYoungLogSuppression {
+    fn drop(&mut self) {
+        BOX_YOUNG_LOG_SUPPRESSED.with(|cell| cell.set(self.0));
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/perry-runtime/src/gc/copying.rs

@@ -1872,9 +1872,23 @@ pub(super) fn run_copied_minor_attempt(
         collector.stats.copied_bytes,
         collector.stats.survivor_live_bytes,
     );
+    if let Some(d) = collector.survival.as_ref() {
+        d.report(super::survival_diag::next_minor_seq());
+    }
+    crate::arena::alloc_sample::report("minor");
+    super::diag_sites::report_primitive_dispatch("minor");
+    crate::object::shapes::id_list_report();
+    report_forwarding_refusals("copying_minor");
+    let scan_us = super::scanner_profile::report_and_reset("copying_minor");
     if crate::gc::gc_diag_enabled() {
+        // This is intentionally the last diagnostic action before returning to
+        // the mutator: `pause_us` prices the whole copied-minor path, including
+        // finalization, pruning, policy feedback and the diagnostic work above.
+        let pause_us = start.elapsed().as_micros() as u64;
         eprintln!(
-            "[gc-copy-minor] ran in_place={} untraced={} untraced_cycles={} untraced_objects={} in_place_blocks={} in_place_dead_bytes={} sparse_blocks={} survival_permille={} copied_objects={} copied_bytes={} promoted_objects={} promoted_bytes={} freed_bytes={} tenuring_survivals={} eden_live_bytes={} trigger={:?} declared_safepoint={}",
+            "[gc-copy-minor] ran pause_us={} scan_us={} in_place={} untraced={} untraced_cycles={} untraced_objects={} in_place_blocks={} in_place_dead_bytes={} sparse_blocks={} survival_permille={} copied_objects={} copied_bytes={} promoted_objects={} promoted_bytes={} freed_bytes={} tenuring_survivals={} eden_live_bytes={} trigger={:?} declared_safepoint={}",
+            pause_us,
+            scan_us,
             collector.stats.in_place_promotion,
             untraced,
             super::untraced_promotion_cycles(),
@@ -1894,14 +1908,6 @@ pub(super) fn run_copied_minor_attempt(
             super::policy::GC_AT_DECLARED_SAFEPOINT.with(std::cell::Cell::get)
         );
     }
-    if let Some(d) = collector.survival.as_ref() {
-        d.report(super::survival_diag::next_minor_seq());
-    }
-    crate::arena::alloc_sample::report("minor");
-    super::diag_sites::report_primitive_dispatch("minor");
-    crate::object::shapes::id_list_report();
-    report_forwarding_refusals("copying_minor");
-    super::scanner_profile::report_and_reset("copying_minor");
     CopiedMinorAttempt::Done(Some(CopiedMinorFastPathOutcome {
         freed_bytes,
         malloc_swept: malloc_sweep_due,

crates/perry-runtime/src/gc/scanner_profile.rs

@@ -128,14 +128,14 @@ pub(super) fn note_scanner(
 
 /// Print the per-scanner breakdown accumulated since the last report, then
 /// clear it. Called once per copied minor from the `[gc-copy-minor]` diag site.
-pub(super) fn report_and_reset(cycle_label: &str) {
+pub(super) fn report_and_reset(cycle_label: &str) -> u64 {
     if !scanner_profile_enabled() {
-        return;
+        return 0;
     }
     super::young_log::report_and_reset(cycle_label);
     let mut rows = SCANNER_PROFILE.with(|rows| std::mem::take(&mut *rows.borrow_mut()));
     if rows.is_empty() {
-        return;
+        return 0;
     }
     rows.sort_by(|a, b| b.1.nanos.cmp(&a.1.nanos));
     let total_ns: u64 = rows.iter().map(|(_, row)| row.nanos).sum();
@@ -159,4 +159,5 @@ pub(super) fn report_and_reset(cycle_label: &str) {
             row.rewrites
         );
     }
+    total_ns / 1000
 }