// ss_hot_prewarm_box.h - Box SS-HotPrewarm
// Phase 20-1: Aggressive TLS SLL + SuperSlab prewarming for page fault reduction
//
// Purpose:
//   - Pre-warm TLS SLL cache with ENV-controlled per-class targets
//   - Reduce page faults by allocating and populating SuperSlabs upfront
//   - Target: 50-66% page fault reduction → +20-40% performance
//
// Design:
//   - ENV controls: HAKMEM_TINY_PREWARM_C2, _C3, _C4, _C5
//   - Default aggressive targets: C2/C3=128, C4/C5=64 (ChatGPT strategy)
//   - Uses Box Prewarm API (box_prewarm_tls) for safe TLS SLL warming
//   - Automatically triggers SuperSlab allocation + populate
//
// ENV Variables:
//   HAKMEM_TINY_PREWARM_C2=N  - Prewarm C2 (33-64B) with N blocks [DEFAULT: 128]
//   HAKMEM_TINY_PREWARM_C3=N  - Prewarm C3 (65-128B) with N blocks [DEFAULT: 128]
//   HAKMEM_TINY_PREWARM_C4=N  - Prewarm C4 (129-256B) with N blocks [DEFAULT: 64]
//   HAKMEM_TINY_PREWARM_C5=N  - Prewarm C5 (257-512B) with N blocks [DEFAULT: 64]
//   HAKMEM_TINY_PREWARM_ALL=N - Override all classes with N blocks [DEFAULT: OFF]
//
// Example:
//   export HAKMEM_TINY_PREWARM_C2=256
//   export HAKMEM_TINY_PREWARM_C3=256
//   ./bench_random_mixed_hakmem

#ifndef HAK_BOX_SS_HOT_PREWARM_H
#define HAK_BOX_SS_HOT_PREWARM_H

#include <stdint.h>
#include <stdbool.h>

// ============================================================================
// Box SS-HotPrewarm API
// ============================================================================

// Pre-warm TLS SLL caches for all Tiny classes based on ENV settings
//
// What it does:
//   1. Read ENV variables (HAKMEM_TINY_PREWARM_C2, etc.)
//   2. For each class with non-zero target:
//      - Call box_prewarm_tls(class_idx, target)
//      - This allocates SuperSlab + populates pages + fills TLS SLL
//   3. Report total blocks pre-warmed
//
// Returns: total blocks pre-warmed across all classes
//
// Thread-safe: uses TLS, call from init only
// Idempotent: safe to call multiple times (subsequent calls are no-op)
//
// Expected impact:
//   - Page faults: -50-66% (amortized upfront)
//   - Performance: +20-40% (per ChatGPT Phase 20 strategy)
//
int box_ss_hot_prewarm_all(void);

// Get prewarm target for a specific class (after ENV parsing)
// Returns: target count, or 0 if no prewarm needed
int box_ss_hot_prewarm_target(int class_idx);

#endif // HAK_BOX_SS_HOT_PREWARM_H