hakmem/docs/status/PHASE19_FRONTEND_METRICS_FINDINGS.md

Phase 19: Frontend Layer Metrics Analysis

Phase 19-1: Box FrontMetrics Implementation ✅

Status: COMPLETE (2025-11-16)

Implementation:

• Created core/box/front_metrics_box.h - Per-class hit/miss counters
• Created core/box/front_metrics_box.c - CSV reporting with percentage analysis
• Added instrumentation to all frontend layers in tiny_alloc_fast.inc.h
• ENV controls: HAKMEM_TINY_FRONT_METRICS=1, HAKMEM_TINY_FRONT_DUMP=1

Build fix: Added missing hakmem_smallmid_superslab.o to Makefile

---

Phase 19-2: Benchmark Results and Analysis ✅

Benchmark: bench_random_mixed_hakmem 500000 4096 42 Workload: Random allocations 16-1040 bytes, 500K iterations

Layer Hit Rates (Classes C2/C3)

Class     UH_hit    HV2_hit     C5_hit     FC_hit    SFC_hit    SLL_hit        Total
------|----------|----------|----------|----------|----------|----------|-------------
C2           455       3,450          0          0          0          0         3,905
C3            13       7,585          0          0          0          0         7,598

Percentages:
C2:  UltraHot=11.7%, HeapV2=88.3%
C3:  UltraHot=0.2%,  HeapV2=99.8%

Key Findings

1. HeapV2 Dominates (>80% hit rate)

   • C2: 88.3% hit rate (3,450 / 3,905 allocations)
   • C3: 99.8% hit rate (7,585 / 7,598 allocations)
   • Recommendation: ✅ Keep and optimize (hot path)

2. UltraHot Marginal (<12% hit rate)

   • C2: 11.7% hit rate (455 / 3,905 allocations)
   • C3: 0.2% hit rate (13 / 7,598 allocations)
   • Recommendation: ⚠️ Consider pruning (low value, adds branch overhead)

3. FastCache DISABLED

   • Gated by g_fastcache_enable=0 (default)
   • 0% hit rate across all classes
   • Status: Not in use (OFF by default)

4. SFC DISABLED

   • Gated by g_sfc_enabled=0 (default)
   • 0% hit rate across all classes
   • Status: Not in use (OFF by default)

5. Class5 Dedicated Path DISABLED

   • g_front_class5_hit[]=0 for all classes
   • Status: Not in use (OFF by default or C5 not hit in this workload)

6. TLS SLL Not Reached

   • 0% hit rate because earlier layers (UltraHot + HeapV2) catch 100%
   • Status: Enabled but bypassed (earlier layers are effective)

Layer Execution Order

FastCache (C0-C3) [DISABLED]
    ↓
SFC (all classes) [DISABLED]
    ↓
UltraHot (C2-C5) [ENABLED] → 0.2-11.7% hit rate
    ↓
HeapV2 (C0-C3) [ENABLED] → 88-99% hit rate ✅
    ↓
Class5 (C5 only) [DISABLED or N/A]
    ↓
TLS SLL (all classes) [ENABLED but not reached]
    ↓
SuperSlab (fallback)

---

Analysis Recommendations (from Box FrontMetrics)

1. Layers with >80% hit rate: ✅ Keep and optimize (hot path)

   • HeapV2: 88-99% hit rate → Primary workhorse for C2/C3

2. Layers with <5% hit rate: ⚠️ Consider pruning (dead weight)

   • FastCache: 0% (disabled)
   • SFC: 0% (disabled)
   • Class5: 0% (disabled or N/A)
   • TLS SLL: 0% (not reached)

3. Multiple layers 5-20%: ⚠️ Potential redundancy, test pruning

   • UltraHot: 0.2-11.7% → Adds branch overhead for minimal benefit

---

Phase 19-3: Next Steps (Box FrontPrune)

Goal: Add ENV switches to selectively disable layers for A/B testing

Proposed ENV Controls:

HAKMEM_TINY_FRONT_DISABLE_ULTRAHOT=1   # Disable UltraHot magazine
HAKMEM_TINY_FRONT_DISABLE_HEAPV2=1     # Disable HeapV2 magazine
HAKMEM_TINY_FRONT_DISABLE_CLASS5=1     # Disable Class5 dedicated path
HAKMEM_TINY_FRONT_ENABLE_FC=1          # Enable FastCache (currently OFF)
HAKMEM_TINY_FRONT_ENABLE_SFC=1         # Enable SFC (currently OFF)

A/B Test Scenarios:

1. Baseline: Current state (UltraHot + HeapV2)
2. Test 1: HeapV2 only (disable UltraHot) → Expected: Minimal perf loss (<12%)
3. Test 2: UltraHot only (disable HeapV2) → Expected: Major perf loss (88-99%)
4. Test 3: Enable FC + SFC, disable UltraHot/HeapV2 → Test classic TLS cache layers
5. Test 4: HeapV2 + FC + SFC (disable UltraHot) → Test hybrid approach

Expected Outcome: Identify minimal effective layer set (maximize hit rate, minimize overhead)

---

Performance Impact

Benchmark Throughput: 10.8M ops/s (500K iterations)

Layer Overhead Estimate:

• Each layer check: ~2-4 instructions (branch + state access)
• Current active layers: UltraHot (2-4 inst) + HeapV2 (2-4 inst) = 4-8 inst overhead
• If UltraHot removed: -2-4 inst = potential +5-10% perf improvement

Risk Assessment:

• Removing HeapV2: HIGH RISK (88-99% hit rate loss)
• Removing UltraHot: LOW RISK (0.2-11.7% hit rate loss, likely <5% perf impact)

---

Files Modified (Phase 19-1)

1. core/box/front_metrics_box.h - NEW (metrics API + inline helpers)
2. core/box/front_metrics_box.c - NEW (CSV reporting)
3. core/tiny_alloc_fast.inc.h - Added metrics collection calls
4. Makefile - Added front_metrics_box.o + hakmem_smallmid_superslab.o

Build Command:

make clean && make HAKMEM_DEBUG_COUNTERS=1 bench_random_mixed_hakmem

Test Command:

HAKMEM_TINY_FRONT_METRICS=1 HAKMEM_TINY_FRONT_DUMP=1 \
./bench_random_mixed_hakmem 500000 4096 42

---

Conclusion

Phase 19-2 successfully identified:

• HeapV2 as the dominant effective layer (>80% hit rate)
• UltraHot as a low-value layer (<12% hit rate)
• FC/SFC as currently unused (disabled by default)

Next Phase: Implement Box FrontPrune ENV switches for A/B testing layer removal.