hakmem/core/box/front_metrics_box.h

// front_metrics_box.h - Box FrontMetrics: Multi-layer frontend hit rate analysis
// Purpose: Measure which frontend layers are actually doing work vs passing through
//
// Phase 19-1: Observation before optimization
// Strategy: Add lightweight counters to all frontend layers, run benchmarks,
//           analyze hit rates to identify:
//           - Layers with high hit率 (keep and optimize)
//           - Layers with low hit率 (consider pruning)
//           - Redundant layers (multiple layers fighting for same workload)
//
// ENV Control:
//   HAKMEM_TINY_FRONT_METRICS=1  - Enable metrics collection
//   HAKMEM_TINY_FRONT_DUMP=1     - Dump metrics at shutdown
//
// Output format (per-class CSV):
//   class, ultrahot_hit, heapv2_hit, class5_hit, fc_hit, sfc_hit, sll_hit, total, ultrahot%, heapv2%, fc%, sfc%, sll%

#ifndef HAK_BOX_FRONT_METRICS_H
#define HAK_BOX_FRONT_METRICS_H

#include <stdint.h>
#include <stdatomic.h>
#include <stdlib.h>  // Phase 19-3: getenv() for FrontPrune

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Phase 19-1: Frontend Layer Hit/Miss Counters (per-class)
// ============================================================================

#ifndef TINY_NUM_CLASSES
#define TINY_NUM_CLASSES 8
#endif

// Layer counters (all __thread to avoid false sharing, atomic for cross-thread visibility)
extern __thread uint64_t g_front_ultrahot_hit[TINY_NUM_CLASSES];
extern __thread uint64_t g_front_ultrahot_miss[TINY_NUM_CLASSES];

extern __thread uint64_t g_front_heapv2_hit[TINY_NUM_CLASSES];
extern __thread uint64_t g_front_heapv2_miss[TINY_NUM_CLASSES];

extern __thread uint64_t g_front_class5_hit[TINY_NUM_CLASSES];
extern __thread uint64_t g_front_class5_miss[TINY_NUM_CLASSES];

// FastCache/SFC/SLL already tracked in hakmem_tiny.c:
// - g_front_fc_hit[] (FastCache)
// - g_front_fc_miss[] (FastCache)
// - g_front_sfc_hit[] (SuperFrontCache)
// - g_front_sll_hit[] (TLS SLL)

// ============================================================================
// API Functions
// ============================================================================

// Check if metrics are enabled (cached)
int front_metrics_enabled(void);

// Dump all frontend metrics to stderr
// Format: CSV table with per-class hit rates and percentages
void hak_tiny_front_metrics_dump(void);

// ============================================================================
// Inline Helpers (zero-cost when metrics disabled)
// ============================================================================

static inline void front_metrics_ultrahot_hit(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_ultrahot_hit[cls]++;
    }
#else
    (void)cls;
#endif
}

static inline void front_metrics_ultrahot_miss(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_ultrahot_miss[cls]++;
    }
#else
    (void)cls;
#endif
}

static inline void front_metrics_heapv2_hit(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_heapv2_hit[cls]++;
    }
#else
    (void)cls;
#endif
}

static inline void front_metrics_heapv2_miss(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_heapv2_miss[cls]++;
    }
#else
    (void)cls;
#endif
}

static inline void front_metrics_class5_hit(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_class5_hit[cls]++;
    }
#else
    (void)cls;
#endif
}

static inline void front_metrics_class5_miss(int cls) {
#if HAKMEM_DEBUG_COUNTERS
    if (front_metrics_enabled()) {
        g_front_class5_miss[cls]++;
    }
#else
    (void)cls;
#endif
}

// Note: FastCache/SFC/SLL counters already managed in hakmem_tiny.c
// No inline helpers needed - we just read their values in dump function

// ============================================================================
// Phase 19-3: Box FrontPrune - ENV-controlled layer pruning for A/B testing
// ============================================================================
// Purpose: Allow selective enabling/disabling of frontend layers
// ENV Controls:
//   HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT=1  - Enable UltraHot magazine (C2-C5) [DEFAULT: OFF]
//   HAKMEM_TINY_FRONT_DISABLE_HEAPV2=1   - Disable HeapV2 magazine (C0-C3) [DEFAULT: ON]
//
// Phase 19-4 A/B Test Result: UltraHot default OFF for +12.9% performance gain
// ============================================================================

static inline int front_prune_ultrahot_enabled(void) {
    static int cached = -1;
    if (__builtin_expect(cached == -1, 0)) {
        const char* env = getenv("HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT");
        cached = (env && *env && *env != '0') ? 1 : 0;  // DEFAULT: OFF (0) for best performance
    }
    return cached;
}

static inline int front_prune_heapv2_enabled(void) {
    static int cached = -1;
    if (__builtin_expect(cached == -1, 0)) {
        const char* env = getenv("HAKMEM_TINY_FRONT_DISABLE_HEAPV2");
        cached = (env && *env && *env != '0') ? 0 : 1;  // DISABLE=1 → return 0
    }
    return cached;
}

#ifdef __cplusplus
}
#endif

#endif // HAK_BOX_FRONT_METRICS_H