hakmem/core/box/smallobject_policy_v7_box.h

// smallobject_policy_v7_box.h - SmallObject Policy v7 (Phase v7-7: Learner integration)
//
// Purpose:
//   - Centralized routing policy for ULTRA / v7 / MID_v3 / LEGACY
//   - Single source of truth for class → route_kind mapping
//   - ENV configuration managed in one place (L3 Policy layer)
//   - Learner: dynamic route switching based on workload stats (v7-7)

#ifndef HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H
#define HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H

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

// ============================================================================
// Route Kind Enum (L0/L1/L1' layer selection)
// ============================================================================

typedef enum {
    SMALL_ROUTE_ULTRA,      // L0: C4-C7 ULTRA (FROZEN)
    SMALL_ROUTE_V7,         // L1: SmallObject v7 (research box)
    SMALL_ROUTE_MID_V3,     // L1': MID v3 (257-768B mid/small)
    SMALL_ROUTE_LEGACY,     // L1': TinyHeap v1 / Pool v1 (fallback)
} SmallRouteKind;

// ============================================================================
// Policy Snapshot Structure
// ============================================================================

typedef struct SmallPolicyV7 {
    SmallRouteKind route_kind[8];  // C0-C7 routing decision
} SmallPolicyV7;

// ============================================================================
// Policy API
// ============================================================================

/// Get policy snapshot (read-only, TLS cached)
/// Frontend calls this to determine route_kind[class_idx]
const SmallPolicyV7* small_policy_v7_snapshot(void);

/// Initialize policy from ENV variables (called once at startup)
/// Priority: ULTRA > v7 > MID_v3 > LEGACY
/// @param policy: Policy structure to initialize
void small_policy_v7_init_from_env(SmallPolicyV7* policy);

/// Get route kind name for debugging
const char* small_route_kind_name(SmallRouteKind kind);

// ============================================================================
// Learner Stats (Phase v7-7)
// ============================================================================

/// Per-class stats for Learner
typedef struct SmallLearnerClassStatsV7 {
    uint64_t total_allocs;      // Total allocs for this class (all routes)
    uint64_t v7_allocs;         // Allocs via v7 route
    uint64_t v7_retires;        // Page retires from v7
    uint32_t sample_count;      // Number of samples
} SmallLearnerClassStatsV7;

/// Aggregate Learner stats
typedef struct SmallLearnerStatsV7 {
    SmallLearnerClassStatsV7 per_class[8];  // C0-C7
    uint64_t total_retires;                  // Total page retires
    uint64_t eval_count;                     // Number of evaluations
} SmallLearnerStatsV7;

// ============================================================================
// Learner API (Phase v7-7)
// ============================================================================

/// Record a page retire for Learner stats (called from ColdIface)
/// @param class_idx: Size class of the retired page
/// @param capacity: Capacity of the page (used as traffic proxy)
void small_learner_v7_record_retire(uint32_t class_idx, uint64_t capacity);

/// Record a page refill for Learner stats (called from ColdIface)
/// @param class_idx: Size class of the refilled page
/// @param capacity: Capacity of the page (used as traffic proxy)
void small_learner_v7_record_refill(uint32_t class_idx, uint64_t capacity);

/// Update policy from Learner stats (called periodically)
/// Decision rule: if C5 alloc ratio > 30%, route C5 to v7, else MID_v3
/// @param stats: Learner stats to evaluate
/// @param policy_out: Policy to update
void small_policy_v7_update_from_learner(
    const SmallLearnerStatsV7* stats,
    SmallPolicyV7* policy_out
);

/// Get current Learner stats snapshot (for debugging/OBSERVE)
const SmallLearnerStatsV7* small_learner_v7_stats_snapshot(void);

/// Force re-evaluation of policy from current stats
void small_learner_v7_evaluate(void);

/// Learner threshold for C5 route decision (default: 30%)
#define SMALL_LEARNER_C5_THRESHOLD_PCT  30

/// Evaluation interval (every N refills)
#define SMALL_LEARNER_EVAL_INTERVAL     100

#endif // HAKMEM_SMALLOBJECT_POLICY_V7_BOX_H