Phase v11a-1: Infrastructure - Multi-class segment and learner v2 box definitions

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 <noreply@anthropic.com>
2025-12-12 06:20:01 +09:00
parent 397aea0131
commit babd884b96
4 changed files with 799 additions and 0 deletions
--- a/core/box/smallobject_policy_v2_box.h
+++ 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 <stdint.h>
+#include <stdbool.h>
+
+#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