hakmem/core/box/smallobject_learner_v2_box.h

// smallobject_learner_v2_box.h
// Phase v11a: Extended Learner for multi-dimensional MID v3.5 optimization

#ifndef SMALLOBJECT_LEARNER_V2_BOX_H
#define SMALLOBJECT_LEARNER_V2_BOX_H

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

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Learner v2 Statistics
// ============================================================================

/**
 * SmallLearnerStatsV2: Per-class and global metrics for route optimization
 *
 * Extends v7 Learner (C5-only ratio) to:
 * - Multi-class allocation tracking
 * - Retire efficiency metrics
 * - Free hit ratio tracking
 * - Global utilization monitoring
 */
typedef struct {
    // Per-class metrics
    uint64_t allocs[8];                 // Allocation count per class
    uint32_t retire_ratio_pct[8];       // Retire efficiency per class (%)
    uint32_t retire_count[8];           // Retired pages per class

    // Global metrics
    uint64_t total_allocations;         // Total allocs across all classes
    uint64_t total_retires;             // Total page retires
    uint64_t avg_page_utilization;      // Average page utilization (basis points)
    uint32_t free_hit_ratio_bps;        // Global free hit rate (basis points, 0-10000)

    // Evaluation state
    uint64_t eval_count;                // Number of evaluations so far
    uint64_t sample_count;              // Total sample points processed
    uint32_t last_eval_timestamp_ms;    // Timestamp of last evaluation

    // Reserved for future extensions
    uint8_t reserved[64];
} SmallLearnerStatsV2;

// ============================================================================
// Per-class Learner State
// ============================================================================

/**
 * SmallLearnerClassStatsV2: Detailed per-class tracking
 * Used internally for exponential smoothing and trend detection
 */
typedef struct {
    uint64_t allocs;                    // Raw allocation count
    uint32_t retire_ratio_smoothed;     // Exponential moving average (%)
    uint32_t sample_count;              // Samples for this class
    uint64_t last_update_ns;
} SmallLearnerClassStatsV2;

// ============================================================================
// Event Recording API
// ============================================================================

/**
 * Record a refill event (page exhausted, need new page)
 * Called from refill path to track allocation pressure
 */
void small_learner_v2_record_refill(uint32_t class_idx, uint64_t capacity);

/**
 * Record a retire event (page freed)
 * Called from retire path with free hit ratio for efficiency tracking
 */
void small_learner_v2_record_retire(uint32_t class_idx,
                                    uint32_t free_hit_ratio_bps);

/**
 * Ingest aggregated stats from stats collector
 * Called periodically by stats module
 */
void small_learner_v2_ingest_stats(const SmallPageStatsAggregate_MID_v3 *agg);

// ============================================================================
// Evaluation & Decision Making
// ============================================================================

/**
 * Trigger learner evaluation
 * Reviews statistics and may update policy routing decisions
 * Called periodically (every SMALL_LEARNER_EVAL_INTERVAL events)
 */
void small_learner_v2_evaluate(void);

/**
 * Get current learner statistics snapshot
 * Returns pointer to internal buffer (valid until next evaluation)
 */
const SmallLearnerStatsV2* small_learner_v2_stats_snapshot(void);

/**
 * Get per-class learner state
 * For debugging/monitoring detailed per-class metrics
 */
const SmallLearnerClassStatsV2* small_learner_v2_class_stats(uint32_t class_idx);

// ============================================================================
// Routing Decision Support
// ============================================================================

/**
 * Query: Should class use v7 or MID_v3?
 * Decision based on C5 ratio (Phase v11a primary decision)
 *
 * Returns:
 *   0 = use MID_v3
 *   1 = use V7 (if enabled)
 */
int small_learner_v2_should_use_v7(uint32_t class_idx);

/**
 * Get C5 allocation ratio (percentage)
 * Used for route decision: C5 ratio >= threshold → v7
 */
uint32_t small_learner_v2_c5_ratio_pct(void);

/**
 * Get class allocation ratio (percentage)
 */
uint32_t small_learner_v2_class_ratio_pct(uint32_t class_idx);

/**
 * Get retire efficiency for class (percentage)
 * Higher = better page utilization before retirement
 */
uint32_t small_learner_v2_retire_efficiency_pct(uint32_t class_idx);

// ============================================================================
// Configuration & Control
// ============================================================================

/**
 * Check if learner is enabled
 * Returns true if HAKMEM_SMALL_LEARNER_V7_ENABLED != 0
 * (Reuses v7 ENV var for backward compatibility)
 */
bool small_learner_v2_enabled(void);

/**
 * Set C5 route decision threshold (percentage)
 * Default: 30 (C5 ratio >= 30% → use v7)
 */
void small_learner_v2_set_c5_threshold_pct(uint32_t threshold);

/**
 * Get C5 threshold
 */
uint32_t small_learner_v2_get_c5_threshold_pct(void);

/**
 * Set evaluation interval (how many events trigger evaluation)
 * Default: SMALL_LEARNER_EVAL_INTERVAL (100)
 */
void small_learner_v2_set_eval_interval(uint32_t interval);

/**
 * Set exponential smoothing factor (0-100)
 * Affects how quickly learner reacts to workload changes
 * Default: 10 (10% new sample, 90% historical average)
 */
void small_learner_v2_set_smoothing_factor(uint32_t factor_pct);

// ============================================================================
// Debugging & Monitoring
// ============================================================================

/**
 * Print learner statistics
 */
void small_learner_v2_print_stats(void);

/**
 * Print routing decisions
 */
void small_learner_v2_print_decisions(void);

/**
 * Enable/disable learner logging (stderr output)
 */
void small_learner_v2_set_logging_enabled(bool enabled);

/**
 * Reset all learner statistics
 */
void small_learner_v2_reset(void);

// ============================================================================
// Constants
// ============================================================================

#ifndef SMALL_LEARNER_EVAL_INTERVAL
#define SMALL_LEARNER_EVAL_INTERVAL 100  // Evaluate every 100 events
#endif

#ifndef SMALL_LEARNER_C5_THRESHOLD_PCT
#define SMALL_LEARNER_C5_THRESHOLD_PCT 30  // Use v7 if C5 >= 30%
#endif

#ifndef SMALL_LEARNER_SMOOTHING_FACTOR_PCT
#define SMALL_LEARNER_SMOOTHING_FACTOR_PCT 10  // 10% new, 90% historical
#endif

// ============================================================================
// Backward Compatibility (v7 interface)
// ============================================================================

// For compatibility with existing v7-style code:
// v7 used SmallLearnerStatsV7 which had per_class[8]
// v2 extends this to include global metrics

// Old code that expects SmallLearnerStatsV7 can still work
// by taking the first part of SmallLearnerStatsV2
typedef SmallLearnerStatsV2 SmallLearnerStatsV7;

#ifdef __cplusplus
}
#endif

#endif // SMALLOBJECT_LEARNER_V2_BOX_H