Switch the GC harnesses to the GC.stat process: keyword

ruby/ruby#19383 (d56354b27b) replaced GC.stat(scope:) with a
process: keyword and make some changes to how counting global GC's work
in the stats.

This commit updates the GC harness, and stats module to report using the
new API

Author: eightbitraptor

README.md

@@ -499,7 +499,8 @@ The `--ractor-gc` option of `run_benchmarks.rb` collects Ractor-local GC
 metrics for benchmarks that use the Ractor harness (`--category ractor`),
 in both the per-worker mode and scenario mode.
 The target must use Ruby 4.1 or newer with per-Ractor global GC attribution
-([ruby/ruby#19147](https://github.com/ruby/ruby/pull/19147)); older targets
+through `GC.stat(:global_gc_invocation_count)` and `GC.stat(process: true)`
+([ruby/ruby#19383](https://github.com/ruby/ruby/pull/19383)); older targets
 fail before warmup.
 
 ```sh
@@ -530,9 +531,11 @@ data when it is zero or `N/A` in every row.
 * Tables marked `worker sum` add the Ractor-local counters and GC times of
   the sampled workers of each iteration. `GCs/iter` is the sum of `minor/iter`,
   `major/iter`, and `global/iter`; a global cycle counts under `global` on
-  the Ractor that initiated it, not under `major`. Single-executable reports
-  also show `GC ms/worker`, which divides each iteration's worker-sum GC
-  time by its sampled worker count, then averages.
+  the Ractor that initiated it (`GC.stat(:global_gc_invocation_count)`), not
+  under `major`. The worker `GCs/iter` excludes global cycles that other
+  Ractors started, so each cycle counts once in the sum. Single-executable
+  reports also show `GC ms/worker`, which divides each iteration's worker-sum
+  GC time by its sampled worker count, then averages.
 * `compacts*` shows the main Ractor's
   `GC.stat(:compact_count)` delta. Every global compacting cycle increments
   it in every object space, so it is not summed across workers.

harness/gc.rb

@@ -30,7 +30,7 @@ def run_benchmark(_num_itrs_hint, **, &block)
 
   has_marking = GC.stat.key?(:marking_time)
   has_sweeping = GC.stat.key?(:sweeping_time)
-  has_global_gc = GCStats.stat_available?(:global_gc_count)
+  has_global_gc = GCStats.stat_available?(:global_gc_invocation_count)
 
   header = "itr:   time"
   header << "   marking" if has_marking
@@ -44,7 +44,6 @@ def run_benchmark(_num_itrs_hint, **, &block)
 
   begin
     gc_before = GCStats.snapshot
-    global_gc_before = GC.stat(:global_gc_count) if has_global_gc
 
     time = realtime(&block)
     num_itrs += 1
@@ -57,7 +56,7 @@ def run_benchmark(_num_itrs_hint, **, &block)
     count_delta = sample["gc_count"]
     major_delta = sample["gc_major_count"]
     minor_delta = sample["gc_minor_count"]
-    global_delta = has_global_gc ? GC.stat(:global_gc_count) - global_gc_before : nil
+    global_delta = sample["gc_global_count"]
     ratio_str = minor_delta > 0 ? "%.2f" % (major_delta.to_f / minor_delta) : "-"
 
     itr_str = "%4s %6s" % ["##{num_itrs}:", "#{time_ms}ms"]

lib/gc_stats.rb

@@ -3,9 +3,8 @@
 module GCStats
   module_function
 
-  SCALAR_FIELDS = [
-    ["gc_count", :count],
-    ["gc_global_count", :global_gc_count],
+  STAT_FIELDS = [
+    ["gc_global_count", :global_gc_invocation_count],
     ["gc_major_count", :major_gc_count],
     ["gc_minor_count", :minor_gc_count],
     ["gc_marking_time", :marking_time],
@@ -14,7 +13,7 @@ module GCStats
 
   TOTAL_TIME_FIELD = "gc_total_time_ns"
 
-  SCALAR_FIELD_NAMES = (SCALAR_FIELDS.map(&:first) + [TOTAL_TIME_FIELD]).freeze
+  SCALAR_FIELD_NAMES = (["gc_count"] + STAT_FIELDS.map(&:first) + [TOTAL_TIME_FIELD]).freeze
 
   RACTOR_SERIES = {
     "gc_count_bench" => "gc_count",
@@ -44,11 +43,15 @@ def global_gc_attributed?
       Warning[:experimental] = false
       $stderr.reopen(File::NULL, "w")
       begin
-        main_before = GC.stat(:global_gc_count)
-        process_before = GC.stat(:global_gc_count, scope: :global)
-        Ractor.new { GC.start(full_mark: true, immediate_mark: true, immediate_sweep: true, global: true) }.join
-        attributed = GC.stat(:global_gc_count) == main_before
-        ran = GC.stat(:global_gc_count, scope: :global) > process_before
+        main_before = GC.stat(:global_gc_invocation_count)
+        process_before = GC.stat(:global_gc_count, process: true)
+        started = Ractor.new do
+          before = GC.stat(:global_gc_invocation_count)
+          GC.start(full_mark: true, immediate_mark: true, immediate_sweep: true, global: true)
+          GC.stat(:global_gc_invocation_count) - before
+        end.value
+        attributed = started == 1 && GC.stat(:global_gc_invocation_count) == main_before
+        ran = GC.stat(:global_gc_count, process: true) > process_before
         exit!(attributed && ran ? 0 : 1)
       rescue StandardError
         exit!(2)
@@ -66,7 +69,7 @@ def check_ractor_gc_support!
       raise NotImplementedError, "Ractor GC metrics require GC.total_time and GC.measure_total_time="
     end
     unless global_gc_attributed?
-      raise NotImplementedError, "Ractor GC metrics require per-Ractor global GC attribution (ruby/ruby#19147)"
+      raise NotImplementedError, "Ractor GC metrics require per-Ractor global GC attribution (ruby/ruby#19383)"
     end
   end
 
@@ -93,17 +96,27 @@ def numeric_delta(before, after)
     after - before if before.is_a?(Numeric) && after.is_a?(Numeric)
   end
 
+  # :count includes global GCs that other Ractors started. Count only the ones
+  # this Ractor started, so that sums across Ractors count each GC once.
+  def started_gc_count(stat)
+    count, swept, started = stat.values_at(:count, :global_gc_count, :global_gc_invocation_count)
+    return count unless [count, swept, started].all?(Numeric)
+
+    count - swept + started
+  end
+
   def snapshot
     {
-      stat: GC.stat(scope: :ractor),
+      stat: GC.stat,
       heap: heap_snapshot,
       total_time_ns: GC.respond_to?(:total_time) ? GC.total_time : nil,
     }
   end
 
   def delta(before, after)
-    sample = SCALAR_FIELDS.each_with_object({}) do |(name, key), result|
-      result[name] = numeric_delta(before[:stat][key], after[:stat][key])
+    sample = { "gc_count" => numeric_delta(started_gc_count(before[:stat]), started_gc_count(after[:stat])) }
+    STAT_FIELDS.each do |name, key|
+      sample[name] = numeric_delta(before[:stat][key], after[:stat][key])
     end
     sample[TOTAL_TIME_FIELD] = numeric_delta(before[:total_time_ns], after[:total_time_ns])
     sample["gc_stat_heap_delta"] = heap_delta(before[:heap], after[:heap])

test/gc_stats_test.rb

@@ -54,6 +54,19 @@ def snapshot(count:, major:, minor:, marking: nil, sweeping: nil, total_ns: nil,
       assert_equal 250_000, GCStats.delta(before, after)['gc_total_time_ns']
     end
 
+    it 'counts only the global GCs that this Ractor started' do
+      before = snapshot(count: 10, major: 2, minor: 5)
+      before[:stat].merge!(global_gc_count: 3, global_gc_invocation_count: 1)
+      after = snapshot(count: 16, major: 2, minor: 6)
+      after[:stat].merge!(global_gc_count: 8, global_gc_invocation_count: 2)
+
+      sample = GCStats.delta(before, after)
+
+      assert_equal 2, sample['gc_count']
+      assert_equal 1, sample['gc_global_count']
+      assert_equal sample['gc_major_count'] + sample['gc_minor_count'] + sample['gc_global_count'], sample['gc_count']
+    end
+
     it 'keeps heap gauge deltas signed and omits heaps/keys absent from the before snapshot' do
       before = snapshot(count: 0, major: 0, minor: 0, heap: {
         0 => { slot_size: 40, heap_eden_slots: 100, heap_live_slots: 50 }
@@ -178,8 +191,8 @@ def snapshot(count:, major:, minor:, marking: nil, sweeping: nil, total_ns: nil,
   end
 
   describe '.global_gc_attributed?' do
-    it 'is false when GC.stat lacks the global_gc_count key' do
-      skip 'this build has the key; attribution depends on ruby/ruby#19147' if GCStats.stat_available?(:global_gc_count)
+    it 'is false when GC.stat lacks the global_gc_invocation_count key' do
+      skip 'this build has the key; attribution depends on ruby/ruby#19383' if GCStats.stat_available?(:global_gc_invocation_count)
       refute GCStats.global_gc_attributed?
     end
   end

test/ractor_gc_harness_test.rb

@@ -189,7 +189,7 @@ def GCStats.global_gc_attributed?(*) = false
 
     _out, attr_err, attr_status = Open3.capture3(CLEAN_ENV, @ruby, '--disable-gems', '-r', File.join(ROOT, 'lib', 'gc_stats'), '-e', 'exit(GCStats.global_gc_attributed? ? 0 : 1)')
     unless attr_status.success?
-      detail = "target #{@ruby} lacks per-Ractor global GC attribution (ruby/ruby#19147): #{attr_err.strip}"
+      detail = "target #{@ruby} lacks per-Ractor global GC attribution (ruby/ruby#19383): #{attr_err.strip}"
       flunk("RACTOR_GC_TEST_RUBY #{detail}") if @explicit_target
       skip("test ruby #{detail}")
     end
@@ -317,9 +317,9 @@ def run_workload(body, env: {})
       worker = Ractor.new do
         GC.disable
         Ractor.receive
-        before = GC.stat(:count, scope: :ractor)
+        before = GC.stat(:count)
         10.times { GC.start(full_mark: false, immediate_sweep: true, global: false) }
-        Ractor.main.send(GC.stat(:count, scope: :ractor) - before)
+        Ractor.main.send(GC.stat(:count) - before)
         Ractor.receive
       end
 
@@ -532,7 +532,7 @@ def run_workload(body, env: {})
   it 'fails before warmup when the target lacks per-Ractor global GC attribution' do
     run_workload(UNATTRIBUTED_GLOBAL_BODY) do |stdout, stderr, status, result_path|
       assert status.success?, "probe script itself failed:\n#{stdout}\n#{stderr}"
-      assert_includes stdout, 'raised: Ractor GC metrics require per-Ractor global GC attribution (ruby/ruby#19147)'
+      assert_includes stdout, 'raised: Ractor GC metrics require per-Ractor global GC attribution (ruby/ruby#19383)'
       assert_includes stdout, 'workload_ran=false'
       refute File.exist?(result_path), 'no results file may be written for an unsupported target'
     end