hakmem/docs/analysis/PHASE70_REFILL_OBSERVABILITY_PREREQS_SSOT.md

Phase 70: Refill Tuning Prerequisites (Observability SSOT)

Status: ✅ COMPLETE (SSOT established)

Context:

• Current baseline (Mixed WS=400 + prefault) generates almost zero cache misses (refills) in Unified Cache.
• Optimizing unified_cache_refill() or Warm Pool logic will yield zero throughput gain if this path is not hot.
• Phase 70 must be gated on observing significant refill activity.
• Current conclusion (WS=400 SSOT): Refill/WarmPool-pop is not hot (misses are extremely low), so refill micro-optimizations are frozen for SSOT workloads; only research workloads should touch refill behavior.

1. Observability Protocol (Step 0)

Before implementing any refill/WarmPool changes, execute this sequence:

0. Route Banner（任意だが推奨）:

   HAKMEM_ROUTE_BANNER=1 ./bench_random_mixed_hakmem_observe ...
   

   • Route assignments（backend route kind）と cache config（unified_cache_enabled / warm_pool_max_per_class）を 1 回だけ表示する。
   • 「Route=LEGACY = Unified Cache 未使用」といった誤認を防ぐ（LEGACYでもUnified Cacheは alloc/free の front で使われる）。

1. Build with Stats:

   make bench_random_mixed_hakmem_observe EXTRA_CFLAGS='-DHAKMEM_UNIFIED_CACHE_STATS_COMPILED=1'
   

   (Note: Phase 70-0 fixed release-mode stats blocking)

2. Run with Stats:

   HAKMEM_ROUTE_BANNER=1 HAKMEM_WARM_POOL_STATS=1 ./bench_random_mixed_hakmem_observe 20000000 400 1
   

3. Check Output:

   • Look for Unified-STATS: miss=...
   • Look for WarmPool-STATS: hits=...

Decision Gate:

• If miss counts are < 1000 (approx <0.01% miss rate):
  • STOP: Optimization has no ROI on this workload.
  • ACTION: Either accept current state (refill is not a bottleneck) or switch to a research workload (below).
• If miss counts are significant:
  • GO: Proceed with Phase 70 logic changes.

2. Research Workload (If Refill Optimization is Mandatory)

If you must measure refill performance improvements (e.g., for architectural validation), modify the workload to force cache pressure:

Option A: Disable Prefault (Cold Path Stress)

HAKMEM_BENCH_PREFAULT=0 ./bench_random_mixed_hakmem_observe ...

• Pros: Forces refills during benchmark loop.
• Cons: Measures startup behavior, not steady-state throughput.

Option B: Increase Working Set (Steady State Stress)

./bench_random_mixed_hakmem_observe 20000000 8192 1  # WS=8192 > Cache(2048)

• Pros: Forces steady-state evictions/refills.
• Cons: Different workload profile than standard Mixed SSOT (WS=400).

WARNING: Do NOT change HAKMEM_TINY_STATIC_ROUTE or ULTRA flags unless specifically testing routing changes. The default LEGACY route does use Unified Cache for alloc/free.

NOTE (Warm Pool sizing semantics):

• HAKMEM_WARM_POOL_SIZE primarily controls the registry-scan prefill cap (warm_pool_max_per_class()).
• The steady-state push-back cap inside unified_cache_refill() is TinyClassPolicy.warm_cap (typically 4/8), so HAKMEM_WARM_POOL_SIZE only matters when registry scans/refills happen often enough to benefit from prefilled slabs.

3. Reference: Why "LEGACY" Route is OK

• LEGACY route means "not ULTRA/MID/V7 specialized".
• Alloc path: malloc_tiny_fast → tiny_hot_alloc_fast → Unified Cache (TLS array).
• Free path: free_tiny_fast → tiny_hot_free_fast → Unified Cache (TLS array).
• Refill path: Cache Miss → unified_cache_refill → Warm Pool → Registry.

Previous confusion ("LEGACY unused") was due to:

1. Stats counting was gated by #if !HAKMEM_BUILD_RELEASE.
2. Low miss rate in WS=400 made it look unused.
3. Phase 70-0 fixed the stats visibility.