Extract random-walk worker controller into shared header

Phase 6 prep. The biased constrained random walk controller introduced
in Phase 5 was only on the GIL parallel-GC code path; the free-threaded
parallel GC (Python/gc_free_threading*.c) has no adaptive worker count
at all. To share IDENTICAL controller behaviour across both builds,
extract the controller logic into a static inline header function:

  Include/internal/pycore_gc_random_walk.h
    _PyGC_RandomWalkUpdate(parallel_time_ns, candidates, &prev_cost,
                           &rng, &adaptive_workers, num_workers)
    _PyGC_RandomWalkSeed(void)  -> initial xorshift32 seed (GC_TEST_SEED
                                   env var or perf counter)

This commit is a pure refactor — no behaviour change. Python/gc.c's
controller body is replaced with the helper call. Python/gc_parallel.c's
seed code (also duplicated of the same logic) is replaced with
_PyGC_RandomWalkSeed().

Next commit will add the controller call site + the corresponding
adaptive_workers/prev_cost_per_obj_ns/explore_rng state and per-worker
condvar dispatch to the free-threaded parallel GC, so both builds
exhibit the same worker-count behaviour.

Verified: GIL build, 124 tests pass (test_gc + test_gc_parallel_mark_alive
+ test_gc_ws_deque). No regression.

Author: SonicField

Include/internal/pycore_gc_random_walk.h

@@ -0,0 +1,117 @@
+// Shared random-walk adaptive worker count controller for parallel GC.
+//
+// Used by both the GIL parallel GC (Python/gc.c, Python/gc_parallel.c) and the
+// free-threaded parallel GC (Python/gc_free_threading*.c) so they exhibit
+// IDENTICAL worker-count adaptation behaviour.
+//
+// Algorithm:
+// - Each collection, with 20% probability, step adaptive_workers by ±1.
+// - 50/50 unbiased direction (no uphill bias).
+// - Clamp result to [2, num_workers].
+// - First collection (prev_cost <= 0) only records baseline; no step.
+//
+// State (caller-owned, must be initialised by caller):
+// - prev_cost_per_obj_ns: previous collection's per-object cost in ns; 0.0
+//   means no measurement yet.
+// - explore_rng: xorshift32 PRNG state; must be non-zero (caller seeds from
+//   GC_TEST_SEED env var or a perf counter, then clamps to 1 if zero).
+// - adaptive_workers: current worker count, in [2, num_workers]; caller
+//   typically initialises to min(4, num_workers).
+
+#ifndef Py_INTERNAL_GC_RANDOM_WALK_H
+#define Py_INTERNAL_GC_RANDOM_WALK_H
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "Python.h"
+#include <stdint.h>
+
+// Update *adaptive_workers, *explore_rng, *prev_cost_per_obj_ns based on the
+// observed collection cost. Pure logic — no allocations, no locks, no globals.
+//
+// parallel_time_ns: wall-clock time the parallel work took (gc_start to
+//   cleanup_end), in nanoseconds. Must be > 0 for the update to fire.
+// candidates: number of objects considered by the collection. Must be > 0 for
+//   the update to fire.
+//
+// If parallel_time_ns <= 0 or candidates <= 0 (e.g. trivial collection),
+// state is not modified.
+static inline void
+_PyGC_RandomWalkUpdate(int64_t parallel_time_ns,
+                       Py_ssize_t candidates,
+                       double *prev_cost_per_obj_ns,
+                       uint32_t *explore_rng,
+                       size_t *adaptive_workers,
+                       size_t num_workers)
+{
+    if (parallel_time_ns <= 0 || candidates <= 0) {
+        return;
+    }
+
+    double cost = (double)parallel_time_ns / (double)candidates;
+    double prev_cost = *prev_cost_per_obj_ns;
+    *prev_cost_per_obj_ns = cost;
+
+    // Skip adjustment on first collection (no baseline yet)
+    if (prev_cost <= 0.0) {
+        return;
+    }
+
+    // xorshift32 PRNG
+    uint32_t rng = *explore_rng;
+    rng ^= rng << 13;
+    rng ^= rng >> 17;
+    rng ^= rng << 5;
+    *explore_rng = rng;
+    double rand_val = (double)(rng & 0xFFFF) / 65535.0;
+
+    // 20% chance to step ±1 (proactive exploration)
+    if (rand_val < 0.2) {
+        // No directional bias: 50/50 chance to increase or decrease
+        double dir_val = (double)((rng >> 16) & 0xFFFF) / 65535.0;
+        int delta = (dir_val < 0.5) ? 1 : -1;
+
+        // Always step when the dice fires. Good values stick because they
+        // don't trigger further corrective steps.
+        size_t trial = *adaptive_workers;
+        if (delta > 0 && trial < num_workers) {
+            trial++;
+        } else if (delta < 0 && trial > 2) {
+            trial--;
+        }
+        *adaptive_workers = trial;
+    }
+}
+
+// Seed an xorshift32 PRNG state. Reads GC_TEST_SEED env var if set
+// (for deterministic tests), otherwise uses PyTime_PerfCounterRaw().
+// Guarantees a non-zero seed (xorshift32 absorbing state).
+static inline uint32_t
+_PyGC_RandomWalkSeed(void)
+{
+    uint32_t seed;
+    const char *seed_env = getenv("GC_TEST_SEED");
+    if (seed_env != NULL) {
+        seed = (uint32_t)atoi(seed_env);
+    } else {
+        PyTime_t seed_time;
+        (void)PyTime_PerfCounterRaw(&seed_time);
+        seed = (uint32_t)seed_time;
+    }
+    if (seed == 0) {
+        seed = 1;  // xorshift32 absorbing state guard
+    }
+    return seed;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !Py_INTERNAL_GC_RANDOM_WALK_H */

Python/gc.c

@@ -9,6 +9,7 @@
 #include "pycore_interp.h"        // PyInterpreterState.gc
 #ifdef Py_PARALLEL_GC
 #include "pycore_gc_parallel.h"   // _PyGC_ParallelMoveUnreachable()
+#include "pycore_gc_random_walk.h"  // _PyGC_RandomWalkUpdate()
 #include "pycore_time.h"          // PyTime_PerfCounterRaw
 #endif
 #include "pycore_interpframe.h"   // _PyFrame_GetLocalsArray()
@@ -2280,46 +2281,15 @@ gc_collect_region(PyThreadState *tstate,
             par_gc->cleanup_end_ns = cleanup_end;
 
             // Biased constrained random walk controller.
-            // Each collection: with 20% probability, step current±1 workers.
-            // Proactive: always step when dice fires. Good values stick naturally.
-            int64_t parallel_time = par_gc->cleanup_end_ns - par_gc->gc_start_ns;
-            Py_ssize_t candidates = par_gc->split_vector.count;
-            if (parallel_time > 0 && candidates > 0) {
-                double cost = (double)parallel_time / (double)candidates;
-                double prev_cost = par_gc->prev_cost_per_obj_ns;
-                par_gc->prev_cost_per_obj_ns = cost;
-
-                // Skip adjustment on first collection (no baseline yet)
-                if (prev_cost <= 0.0) {
-                    goto controller_done;
-                }
-
-                // xorshift32 PRNG
-                uint32_t rng = par_gc->explore_rng;
-                rng ^= rng << 13;
-                rng ^= rng >> 17;
-                rng ^= rng << 5;
-                par_gc->explore_rng = rng;
-                double rand_val = (double)(rng & 0xFFFF) / 65535.0;
-
-                // 20% chance to step ±1 (proactive exploration)
-                if (rand_val < 0.2) {
-                    // No directional bias: 50/50 chance to increase or decrease
-                    double dir_val = (double)((rng >> 16) & 0xFFFF) / 65535.0;
-                    int delta = (dir_val < 0.5) ? 1 : -1;
-
-                    // Always step when the dice fires. Good values stick
-                    // because they don't trigger further corrective steps.
-                    size_t trial = par_gc->adaptive_workers;
-                    if (delta > 0 && trial < par_gc->num_workers) {
-                        trial++;
-                    } else if (delta < 0 && trial > 2) {
-                        trial--;
-                    }
-                    par_gc->adaptive_workers = trial;
-                }
-controller_done: ;
-            }
+            // Shared with the free-threaded parallel GC for identical
+            // behaviour across builds — see pycore_gc_random_walk.h.
+            _PyGC_RandomWalkUpdate(
+                par_gc->cleanup_end_ns - par_gc->gc_start_ns,
+                par_gc->split_vector.count,
+                &par_gc->prev_cost_per_obj_ns,
+                &par_gc->explore_rng,
+                &par_gc->adaptive_workers,
+                par_gc->num_workers);
         }
     }
 #endif

Python/gc_parallel.c

@@ -5,6 +5,7 @@
 #ifdef Py_PARALLEL_GC
 
 #include "pycore_gc_parallel.h"
+#include "pycore_gc_random_walk.h"  // _PyGC_RandomWalkSeed()
 #include "pycore_pystate.h"
 #include "pycore_interp.h"
 #include "pycore_gc.h"  // For GC internals
@@ -507,17 +508,7 @@ _PyGC_ParallelInit(PyInterpreterState *interp, size_t num_workers)
     par_gc->prev_cost_per_obj_ns = 0.0;  // no previous measurement yet
 
     // Seed PRNG from GC_TEST_SEED or perf counter
-    const char *seed_env = getenv("GC_TEST_SEED");
-    if (seed_env != NULL) {
-        par_gc->explore_rng = (uint32_t)atoi(seed_env);
-    } else {
-        PyTime_t seed_time;
-        (void)PyTime_PerfCounterRaw(&seed_time);
-        par_gc->explore_rng = (uint32_t)seed_time;
-    }
-    if (par_gc->explore_rng == 0) {
-        par_gc->explore_rng = 1;  // xorshift32 absorbing state guard
-    }
+    par_gc->explore_rng = _PyGC_RandomWalkSeed();
 
     par_gc->dispatch_in_progress = 0;