hakmem/core/box/tiny_front_config_box.h

// tiny_front_config_box.h - Phase 4-Step3: Tiny Front Config Box
// Purpose: Compile-time configuration for dead code elimination
// Contract: Dual-mode (compile-time fixed vs. runtime ENV checks)
// Performance: Target +5-8% via branch elimination (57.2M → 60-62M ops/s)
//
// Design Principles (Box Pattern):
// 1. Single Responsibility: Configuration management ONLY
// 2. Clear Contract: PGO mode = compile-time constants, Normal mode = runtime checks
// 3. Observable: Config report function (debug builds)
// 4. Safe: Backward compatible (default runtime mode)
// 5. Testable: Easy A/B comparison (PGO vs normal builds)
//
// Usage:
//   Normal build (runtime config, backward compatible):
//     make bench_random_mixed_hakmem
//
//   PGO build (compile-time config, dead code elimination):
//     make CFLAGS="-DHAKMEM_TINY_FRONT_PGO=1" bench_random_mixed_hakmem
//
// Expected Benefit:
//   - Dead code elimination: Compiler removes disabled code paths
//   - Branch reduction: if (CONSTANT_0) { ... } → eliminated
//   - I-cache improvement: Smaller code size (no dead branches)
//   - Target: +5-8% improvement (even without PGO profiling)

#ifndef TINY_FRONT_CONFIG_BOX_H
#define TINY_FRONT_CONFIG_BOX_H

#include <stdio.h>
#include "../hakmem_build_flags.h"

// ============================================================================
// Build Flag Check (must be defined in hakmem_build_flags.h)
// ============================================================================

#ifndef HAKMEM_TINY_FRONT_PGO
#  define HAKMEM_TINY_FRONT_PGO 0
#endif

// ============================================================================
// PGO Mode: Fixed Configuration (Compile-Time Constants)
// ============================================================================

#if HAKMEM_TINY_FRONT_PGO

// PGO-optimized build: All runtime checks become compile-time constants
// Compiler constant folding eliminates dead branches:
//   if (TINY_FRONT_HEAP_V2_ENABLED) { ... }  // 0 → entire block removed
//   if (!TINY_FRONT_SFC_ENABLED) { ... }     // !1 → entire block removed

#define TINY_FRONT_ULTRA_SLIM_ENABLED    0   // Disabled (use normal front)
#define TINY_FRONT_HEAP_V2_ENABLED       0   // Disabled (use Unified Cache)
#define TINY_FRONT_SFC_ENABLED           1   // Enabled (SFC cascade)
#define TINY_FRONT_FASTCACHE_ENABLED     0   // Disabled (use Unified Cache)
#define TINY_FRONT_UNIFIED_GATE_ENABLED  1   // Enabled (Front Gate Unification)
#define TINY_FRONT_METRICS_ENABLED       0   // Disabled (no runtime overhead)
#define TINY_FRONT_DIAG_ENABLED          0   // Disabled (no diagnostics)

// Expected code reduction:
//   - Ultra SLIM check: 1 branch removed
//   - Heap V2 check: 1 branch removed
//   - Metrics check: 2-3 branches removed
//   - Diag check: 1 branch removed
//   Total: 5-7 branches eliminated in hot path

#else

// ============================================================================
// Normal Mode: Runtime Configuration (Backward Compatible)
// ============================================================================

// Normal build: Checks ENV variables or global config state
// Preserves backward compatibility with existing ENV variable interface
//
// NOTE: The actual runtime config functions (ultra_slim_mode_enabled, etc.)
// are defined in their respective modules:
//   - front_gate_unified_enabled() → core/front/malloc_tiny_fast.h
//   - sfc_cascade_enabled() → core/hakmem_tiny_sfc.h
//   - tiny_heap_v2_enabled() → core/front/tiny_heap_v2.h
//   - etc.
//
// This config box ONLY defines the macros that expand to function calls.
// The functions themselves must be included/defined before using these macros.

// Config macros (runtime function calls)
// These expand to actual function calls in normal mode
#define TINY_FRONT_ULTRA_SLIM_ENABLED    ultra_slim_mode_enabled()
#define TINY_FRONT_HEAP_V2_ENABLED       tiny_heap_v2_enabled()
#define TINY_FRONT_SFC_ENABLED           sfc_cascade_enabled()
#define TINY_FRONT_FASTCACHE_ENABLED     tiny_fastcache_enabled()
#define TINY_FRONT_UNIFIED_GATE_ENABLED  front_gate_unified_enabled()
#define TINY_FRONT_METRICS_ENABLED       tiny_metrics_enabled()
#define TINY_FRONT_DIAG_ENABLED          tiny_diag_enabled()

#endif // HAKMEM_TINY_FRONT_PGO

// ============================================================================
// Configuration Helpers
// ============================================================================

// Check if running in PGO-optimized build
static inline int tiny_front_is_pgo_build(void) {
    return HAKMEM_TINY_FRONT_PGO;
}

// Get effective configuration (for diagnostics)
static inline void tiny_front_config_report(void) {
#if !HAKMEM_BUILD_RELEASE
    fprintf(stderr, "[TINY_FRONT_CONFIG]\n");
    fprintf(stderr, "  PGO Build: %d\n", HAKMEM_TINY_FRONT_PGO);
    fprintf(stderr, "  Ultra SLIM: %d\n", TINY_FRONT_ULTRA_SLIM_ENABLED);
    fprintf(stderr, "  Heap V2: %d\n", TINY_FRONT_HEAP_V2_ENABLED);
    fprintf(stderr, "  SFC: %d\n", TINY_FRONT_SFC_ENABLED);
    fprintf(stderr, "  FastCache: %d\n", TINY_FRONT_FASTCACHE_ENABLED);
    fprintf(stderr, "  Unified Gate: %d\n", TINY_FRONT_UNIFIED_GATE_ENABLED);
    fprintf(stderr, "  Metrics: %d\n", TINY_FRONT_METRICS_ENABLED);
    fprintf(stderr, "  Diag: %d\n", TINY_FRONT_DIAG_ENABLED);
    fflush(stderr);
#endif
}

// ============================================================================
// Performance Notes
// ============================================================================

// Expected improvements (Phase 4-Step3):
// - Random Mixed 256: 57.2M → 60-62M ops/s (+5-8%)
// - Tiny Hot 64B: Current → +5-8%
//
// Key optimizations:
// 1. Dead code elimination: Compiler removes disabled code paths
// 2. Branch reduction: if (CONSTANT) → compile-time evaluation
// 3. I-cache improvement: Smaller code size (no dead branches)
// 4. Constant propagation: Compiler optimizes based on known values
//
// Trade-offs:
// 1. Binary size: PGO build is specialized (not configurable at runtime)
// 2. Flexibility: PGO build ignores ENV variables (fixed config)
// 3. Testing: Need separate builds for A/B testing (PGO vs normal)
//
// Recommendation:
// - Development: Use normal build (runtime config, flexible)
// - Production: Use PGO build after profiling (maximum performance)

#endif // TINY_FRONT_CONFIG_BOX_H