From babd884b96cf2e50163ac0b04c52e576ecaf63c1 Mon Sep 17 00:00:00 2001 From: "Moe Charm (CI)" Date: Fri, 12 Dec 2025 06:20:01 +0900 Subject: [PATCH] Phase v11a-1: Infrastructure - Multi-class segment and learner v2 box definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create core box definitions for MID v3.5 consolidation (Phase v11a): 1. smallobject_segment_mid_v3_box.h - Multi-class unified segment (2MiB, C5-C7) - Per-class free page stacks - SmallHeapCtx_MID_v3 for TLS caching - Refill/retire/validation APIs 2. smallobject_stats_mid_v3_box.h - SmallPageStatsMID_v3: per-page lifetime stats - Aggregation for Learner input - Free hit ratio tracking (basis points) 3. smallobject_learner_v2_box.h - SmallLearnerStatsV2: multi-class and global metrics - Extended from v7 (C5-only ratio) to full workload analysis - Per-class retire efficiency, global free hit ratio - Decision API for route optimization 4. smallobject_policy_v2_box.h - SmallPolicyV2: routing with Learner integration - Version-based TLS cache invalidation - Route update from Learner stats - Backward compatible with v1 interface Dependency graph: segment → stats → learner → policy → malloc routing Architecture Decision: Option A (MID v3.5 consolidation) - v7 frozen as C5/C6-only research preset - MID v3.5 becomes 257-1KiB main implementation - Learner scope: multi-class tracking (C5 ratio primary, Phase v11a) - Future (v11b): multi-dimensional optimization 🤖 Generated with Claude Code Co-Authored-By: Claude Haiku 4.5 --- core/box/smallobject_learner_v2_box.h | 231 ++++++++++++++++++++++ core/box/smallobject_policy_v2_box.h | 206 +++++++++++++++++++ core/box/smallobject_segment_mid_v3_box.h | 193 ++++++++++++++++++ core/box/smallobject_stats_mid_v3_box.h | 169 ++++++++++++++++ 4 files changed, 799 insertions(+) create mode 100644 core/box/smallobject_learner_v2_box.h create mode 100644 core/box/smallobject_policy_v2_box.h create mode 100644 core/box/smallobject_segment_mid_v3_box.h create mode 100644 core/box/smallobject_stats_mid_v3_box.h diff --git a/core/box/smallobject_learner_v2_box.h b/core/box/smallobject_learner_v2_box.h new file mode 100644 index 00000000..11604722 --- /dev/null +++ b/core/box/smallobject_learner_v2_box.h @@ -0,0 +1,231 @@ +// 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 +#include + +#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 diff --git a/core/box/smallobject_policy_v2_box.h b/core/box/smallobject_policy_v2_box.h new file mode 100644 index 00000000..0a4cf05a --- /dev/null +++ b/core/box/smallobject_policy_v2_box.h @@ -0,0 +1,206 @@ +// smallobject_policy_v2_box.h +// Phase v11a: Policy Box v2 with extended Learner integration + +#ifndef SMALLOBJECT_POLICY_V2_BOX_H +#define SMALLOBJECT_POLICY_V2_BOX_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +// ============================================================================ +// Route Kinds (Shared with Policy v1) +// ============================================================================ + +typedef enum { + SMALL_ROUTE_ULTRA = 0, // ULTRA fast path (C4-C7) + SMALL_ROUTE_V7 = 1, // SmallObject v7 research box (C5/C6) + SMALL_ROUTE_MID_V3 = 2, // MID v3.5 main box (C5-C7) + SMALL_ROUTE_LEGACY = 3, // Legacy fallback (all classes) +} SmallRouteKind; + +// ============================================================================ +// Policy State (Extended from v1) +// ============================================================================ + +/** + * SmallPolicyV2: Routing decision table with version tracking + * + * Extends SmallPolicyV7 with: + * - Version-based TLS invalidation (atomic updates) + * - Integration point for Learner v2 + * - Support for multi-class MID v3.5 + */ +typedef struct { + uint8_t route_kind[8]; // Route per class index (C0-C7) + uint32_t policy_version; // Version for TLS cache invalidation + uint64_t last_update_timestamp_ms; // When policy was last updated + uint32_t learner_eval_count; // How many times learner updated this + uint8_t reserved[32]; // For future extensions +} SmallPolicyV2; + +// ============================================================================ +// Policy Lifecycle +// ============================================================================ + +/** + * Get thread-local policy snapshot + * This is the main entry point for routing decisions + * + * Policy snapshot is cached in TLS: + * - If version matches global version: return cached snapshot + * - Otherwise: re-initialize from ENV and apply Learner updates + * + * Returns pointer to TLS-local SmallPolicyV2 (valid until next call) + */ +const SmallPolicyV2* small_policy_v2_snapshot(void); + +/** + * Initialize policy from environment variables + * Called on first access or when version mismatch detected + * + * Reads ENV: + * HAKMEM_TINY_C7_ULTRA_ENABLED → route[7] = ULTRA + * HAKMEM_SMALL_HEAP_V7_ENABLED → route[5/6] = V7 + * HAKMEM_SMALL_HEAP_V7_CLASSES → which classes for v7 + * HAKMEM_MID_V3_ENABLED → route[5/6/7] = MID_V3 + * HAKMEM_MID_V3_CLASSES → which classes for MID_v3 + */ +void small_policy_v2_init_from_env(SmallPolicyV2 *policy); + +// ============================================================================ +// Learner Integration +// ============================================================================ + +/** + * Update policy based on learner statistics + * Called when learner detects workload change (route switch opportunity) + * + * Decision logic (Phase v11a): + * - C5 ratio >= threshold AND v7 available → route[5] = V7 + * - C5 ratio < threshold → route[5] = MID_V3 + * + * May be extended (Phase v11b) for multi-dimensional decisions: + * - retire_efficiency, free_hit_ratio, fragmentation, etc. + */ +void small_policy_v2_update_from_learner( + const SmallLearnerStatsV2 *stats, + SmallPolicyV2 *policy_out +); + +/** + * Called by learner after route decision + * Invalidates TLS policy caches so next access gets updated policy + */ +void small_policy_v2_invalidate_tls_cache(void); + +// ============================================================================ +// Route Accessors +// ============================================================================ + +/** + * Get route for class index + * Returns SmallRouteKind for class_idx (C0-C7) + */ +SmallRouteKind small_policy_v2_get_route(uint32_t class_idx); + +/** + * Get route name string (for debugging/logging) + */ +const char* small_policy_v2_route_name(SmallRouteKind route); + +/** + * Check if class is supported by specific route + */ +bool small_policy_v2_route_supports_class(SmallRouteKind route, + uint32_t class_idx); + +// ============================================================================ +// Configuration & Control +// ============================================================================ + +/** + * Set global policy version + * Called by learner to trigger TLS cache invalidation + * Internal API + */ +void small_policy_v2_set_version(uint32_t version); + +/** + * Get current policy version + */ +uint32_t small_policy_v2_get_version(void); + +/** + * Check if TLS policy cache is stale + * (version != global version) + */ +bool small_policy_v2_tls_cache_stale(void); + +/** + * Force policy re-evaluation + * Useful for ENV variable changes at runtime + */ +void small_policy_v2_reload_from_env(void); + +// ============================================================================ +// Debugging & Monitoring +// ============================================================================ + +/** + * Print current policy routing table + * Shows which route each class is assigned to + */ +void small_policy_v2_print_routing(void); + +/** + * Print policy history + * Shows recent policy changes (for learner effectiveness monitoring) + */ +void small_policy_v2_print_history(void); + +/** + * Get policy statistics + */ +typedef struct { + uint32_t total_route_switches; + uint32_t learner_driven_switches; + uint32_t env_driven_reloads; + uint64_t last_switch_timestamp_ms; + char last_switch_description[128]; +} SmallPolicyStats_V2; + +SmallPolicyStats_V2 small_policy_v2_get_stats(void); + +// ============================================================================ +// Constants & Configuration +// ============================================================================ + +#ifndef SMALL_ROUTE_PRIORITY_NONE +// Priority order (highest to lowest): +// 1. ULTRA (if enabled for class) +// 2. V7 (if enabled and Learner decides) +// 3. MID_V3 (if enabled, usually default) +// 4. LEGACY (fallback for all classes) +#define SMALL_ROUTE_PRIORITY_NONE 0 +#endif + +// ============================================================================ +// Backward Compatibility +// ============================================================================ + +// For code that uses v1 types: +// typedef SmallPolicyV2 SmallPolicyV7; // Can be added if needed + +// Old function names can be aliased: +// #define small_policy_v7_snapshot() small_policy_v2_snapshot() +// etc. + +#ifdef __cplusplus +} +#endif + +#endif // SMALLOBJECT_POLICY_V2_BOX_H diff --git a/core/box/smallobject_segment_mid_v3_box.h b/core/box/smallobject_segment_mid_v3_box.h new file mode 100644 index 00000000..09832930 --- /dev/null +++ b/core/box/smallobject_segment_mid_v3_box.h @@ -0,0 +1,193 @@ +// smallobject_segment_mid_v3_box.h +// Phase v11a: Multi-class unified segment for MID v3.5 (C5-C7, 257-1KiB) + +#ifndef SMALLOBJECT_SEGMENT_MID_V3_BOX_H +#define SMALLOBJECT_SEGMENT_MID_V3_BOX_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +// ============================================================================ +// SmallSegment_MID_v3: Unified 2MiB segment for C5-C7 allocations +// ============================================================================ + +// Multi-class segment geometry +typedef struct { + void *start; // Segment start address + size_t total_size; // 2 MiB (fixed) + size_t page_size; // 64 KiB (fixed) + uint32_t num_pages; // 32 pages total + + // Per-class free page stacks (LIFO) + void **free_pages[8]; // free_pages[class_idx] → page pointers + uint32_t free_count[8]; // Free page count per class + + // Current allocation page per class + void *current_page[8]; // Current page for class + uint32_t page_offset[8]; // Allocation offset in current page + + // Page metadata array + struct SmallPageMeta **pages; // [32] → SmallPageMeta for each page + + // Region identification (for RegionIdBox lookup) + uint32_t region_id; // Assigned by RegionIdBox + + // Statistics + uint64_t total_allocations; + uint64_t total_frees; + uint32_t last_refill_count; // For Learner evaluation interval +} SmallSegment_MID_v3; + +// TLS context for MID_v3 fast path +typedef struct { + SmallSegment_MID_v3 *seg; // Segment pointer + void *page[8]; // TLS cached current page per class + uint32_t offset[8]; // TLS cached offset per class + uint32_t cache_hits; // Stats: TLS cache hit count + uint32_t cache_misses; // Stats: TLS cache miss count +} SmallHeapCtx_MID_v3; + +// ============================================================================ +// Segment Lifecycle API +// ============================================================================ + +/** + * Create a new SmallSegment_MID_v3 + * Allocates 2 MiB contiguous memory and initializes per-class metadata + * Returns NULL on failure + */ +SmallSegment_MID_v3* small_segment_mid_v3_create(void); + +/** + * Destroy and deallocate a segment + * Assumes all pages have been retired + */ +void small_segment_mid_v3_destroy(SmallSegment_MID_v3 *seg); + +/** + * Get region ID assigned to this segment (by RegionIdBox) + */ +uint32_t small_segment_mid_v3_region_id(SmallSegment_MID_v3 *seg); + +/** + * Set region ID (called by RegionIdBox during registration) + */ +void small_segment_mid_v3_set_region_id(SmallSegment_MID_v3 *seg, + uint32_t region_id); + +// ============================================================================ +// Fast Allocation Path +// ============================================================================ + +/** + * Fast allocation within segment (TLS cached path) + * Called from hot path after checking TLS cache hit + * Returns pointer or NULL if allocation failed + */ +void* small_segment_mid_v3_alloc_fast( + SmallHeapCtx_MID_v3 *ctx, + uint32_t class_idx, + size_t size +); + +/** + * Slow allocation path (refill or new page) + * Called when TLS fast path fails + */ +void* small_segment_mid_v3_alloc_slow( + SmallSegment_MID_v3 *seg, + uint32_t class_idx, + size_t size, + SmallHeapCtx_MID_v3 *ctx_update +); + +/** + * Refill current page for class + * Gets next free page from free stack or allocates from segment + * Returns true if refill succeeded + */ +bool small_segment_mid_v3_refill_page( + SmallSegment_MID_v3 *seg, + uint32_t class_idx, + SmallHeapCtx_MID_v3 *ctx_update +); + +// ============================================================================ +// Page Lifecycle +// ============================================================================ + +/** + * Retire a full page back to free stack + * Records stats for Learner + * Called from ColdIface path + */ +void small_segment_mid_v3_retire_page( + SmallSegment_MID_v3 *seg, + uint32_t class_idx, + void *page +); + +/** + * Check if page is within segment bounds + */ +bool small_segment_mid_v3_contains_page(SmallSegment_MID_v3 *seg, + void *page); + +/** + * Get page metadata for pointer + * Returns SmallPageMeta or NULL if invalid + */ +struct SmallPageMeta* small_segment_mid_v3_get_page_meta( + SmallSegment_MID_v3 *seg, + void *page +); + +// ============================================================================ +// Statistics & Monitoring +// ============================================================================ + +/** + * Get segment-wide statistics + */ +typedef struct { + uint64_t total_allocations; + uint64_t total_frees; + uint32_t total_pages_allocated; + uint32_t total_pages_freed; + uint32_t active_pages[8]; // Active pages per class +} SmallSegmentStatsMID_v3; + +SmallSegmentStatsMID_v3 small_segment_mid_v3_get_stats( + SmallSegment_MID_v3 *seg +); + +/** + * Reset statistics + */ +void small_segment_mid_v3_reset_stats(SmallSegment_MID_v3 *seg); + +// ============================================================================ +// Validation & Debugging +// ============================================================================ + +/** + * Validate segment integrity + * Returns false if corruption detected + */ +bool small_segment_mid_v3_validate(SmallSegment_MID_v3 *seg); + +/** + * Debug: print segment layout + */ +void small_segment_mid_v3_debug_print(SmallSegment_MID_v3 *seg); + +#ifdef __cplusplus +} +#endif + +#endif // SMALLOBJECT_SEGMENT_MID_V3_BOX_H diff --git a/core/box/smallobject_stats_mid_v3_box.h b/core/box/smallobject_stats_mid_v3_box.h new file mode 100644 index 00000000..0fbbe7a8 --- /dev/null +++ b/core/box/smallobject_stats_mid_v3_box.h @@ -0,0 +1,169 @@ +// smallobject_stats_mid_v3_box.h +// Phase v11a: Stats collection for MID v3.5 page lifetime tracking + +#ifndef SMALLOBJECT_STATS_MID_V3_BOX_H +#define SMALLOBJECT_STATS_MID_V3_BOX_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +// ============================================================================ +// Page Statistics (Published on retire) +// ============================================================================ + +/** + * SmallPageStatsMID_v3: Statistics for a single page lifetime + * Recorded when page is retired (freed) + * Fed to Learner for route optimization + */ +typedef struct { + uint32_t class_idx; // Size class (C5-C7, 5-7) + uint64_t total_allocations; // Number of allocations on this page + uint64_t total_frees; // Number of frees on this page + uint32_t page_alloc_count; // Total slots on page (capacity) + uint32_t free_hit_ratio_bps; // Free hit rate in basis points (0-10000) + uint64_t lifetime_ns; // Page lifetime in nanoseconds +} SmallPageStatsMID_v3; + +/** + * Published stats event + * Includes timestamp and pointer for tracing + */ +typedef struct { + SmallPageStatsMID_v3 stat; + void *page_ptr; + uint64_t retire_timestamp_ns; + uint64_t sequence_number; // For ordering stats stream +} SmallPageStatsPublished_MID_v3; + +// ============================================================================ +// Stats Publishing & Collection +// ============================================================================ + +/** + * Publish page statistics (called during page retire) + * This is the main entry point from ColdIface + */ +void small_stats_mid_v3_publish(const SmallPageStatsMID_v3 *stat); + +/** + * Get the latest published stat (for debugging/monitoring) + * Returns pointer to internal buffer (valid until next publish) + */ +const SmallPageStatsPublished_MID_v3* small_stats_mid_v3_latest(void); + +/** + * Get total stats published so far + */ +uint64_t small_stats_mid_v3_published_count(void); + +// ============================================================================ +// Periodic Aggregation (for Learner) +// ============================================================================ + +/** + * SmallPageStatsAggregate_MID_v3: Aggregated stats for Learner input + * Computed periodically (on evaluation interval) + */ +typedef struct { + // Per-class aggregates + uint64_t class_allocations[8]; // Total allocs per class + uint64_t class_frees[8]; // Total frees per class + uint32_t class_retire_count[8]; // Retired pages per class + uint32_t class_avg_free_hit_bps[8]; // Avg free hit ratio per class + + // Global metrics + uint64_t total_allocations; + uint64_t total_frees; + uint32_t total_pages_retired; + uint32_t global_avg_free_hit_bps; // Weighted average + uint64_t aggregate_timestamp_ns; + uint64_t eval_count; // Evaluation cycle counter +} SmallPageStatsAggregate_MID_v3; + +/** + * Trigger stats aggregation + * Called periodically by Learner + */ +void small_stats_mid_v3_aggregate(SmallPageStatsAggregate_MID_v3 *out); + +/** + * Get snapshot of current aggregated stats + * Returns pointer to internal buffer + */ +const SmallPageStatsAggregate_MID_v3* small_stats_mid_v3_aggregate_snapshot(void); + +// ============================================================================ +// Learner Feed Integration +// ============================================================================ + +/** + * Callback: Stats are ready for Learner + * Called after aggregation to notify Learner subsystem + * Implementation in smallobject_learner_v2.c + */ +void small_learner_v2_ingest_stats_mid_v3( + const SmallPageStatsAggregate_MID_v3 *agg +); + +// ============================================================================ +// Configuration +// ============================================================================ + +/** + * Set evaluation interval (how often to aggregate for Learner) + * Default: SMALL_STATS_EVAL_INTERVAL (100 page retires) + */ +void small_stats_mid_v3_set_eval_interval(uint32_t interval); + +/** + * Get current evaluation interval + */ +uint32_t small_stats_mid_v3_get_eval_interval(void); + +// ============================================================================ +// Debugging & Monitoring +// ============================================================================ + +/** + * Print latest stats + */ +void small_stats_mid_v3_print_latest(void); + +/** + * Print aggregated stats + */ +void small_stats_mid_v3_print_aggregate(void); + +/** + * Enable/disable stats collection (performance tuning) + * Default: enabled when MID_v3 enabled + */ +void small_stats_mid_v3_set_enabled(bool enabled); + +/** + * Reset all accumulated stats + */ +void small_stats_mid_v3_reset(void); + +// ============================================================================ +// Constants +// ============================================================================ + +#ifndef SMALL_STATS_EVAL_INTERVAL +#define SMALL_STATS_EVAL_INTERVAL 100 // Evaluate every 100 page retires +#endif + +#ifndef SMALL_STATS_HISTORY_SIZE +#define SMALL_STATS_HISTORY_SIZE 1000 // Keep last 1000 published stats +#endif + +#ifdef __cplusplus +} +#endif + +#endif // SMALLOBJECT_STATS_MID_V3_BOX_H