From 9830237d56568c444f8bc260ade2cb5dc6b14637 Mon Sep 17 00:00:00 2001
From: "Moe Charm (CI)" <moecharm@example.com>
Date: Fri, 14 Nov 2025 07:59:33 +0900
Subject: [PATCH] Phase 12: SP-SLOT Box data structures (Task SP-1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added per-slot state management for Shared SuperSlab Pool optimization.

Problem:
- Current: 1 SuperSlab mixes multiple classes (C0-C7)
- SuperSlab freed only when ALL classes empty (active_slabs==0)
- Result: SuperSlabs rarely freed, LRU cache unused

Solution: SP-SLOT Box
- Track each slab slot state: UNUSED/ACTIVE/EMPTY
- Per-class free slot lists for efficient reuse
- Free SuperSlab only when ALL slots empty

New Structures:
1. SlotState enum - Per-slot state (UNUSED/ACTIVE/EMPTY)
2. SharedSlot - Per-slot metadata (state, class_idx, slab_idx)
3. SharedSSMeta - Per-SuperSlab slot array management
4. FreeSlotList - Per-class free slot lists

Extended SharedSuperSlabPool:
- free_slots[TINY_NUM_CLASSES_SS] - Per-class lists
- ss_metadata[] - SuperSlab metadata array

Next Steps:
- Task SP-2: Implement 3-stage acquire_slab logic
- Task SP-3: Convert release_slab to slot-based
- Expected: Significant mmap/munmap reduction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 core/hakmem_shared_pool.c |  7 ++++-
 core/hakmem_shared_pool.h | 65 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/core/hakmem_shared_pool.c b/core/hakmem_shared_pool.c
index a72f1f09..13e4af13 100644
--- a/core/hakmem_shared_pool.c
+++ b/core/hakmem_shared_pool.c
@@ -25,7 +25,12 @@ SharedSuperSlabPool g_shared_pool = {
     .class_hints  = { NULL },
     .lru_head     = NULL,
     .lru_tail     = NULL,
-    .lru_count    = 0
+    .lru_count    = 0,
+    // Phase 12: SP-SLOT fields
+    .free_slots   = {{.entries = {{0}}, .count = 0}},  // Zero-init all class free lists
+    .ss_metadata  = NULL,
+    .ss_meta_capacity = 0,
+    .ss_meta_count = 0
 };
 
 static void
diff --git a/core/hakmem_shared_pool.h b/core/hakmem_shared_pool.h
index 673a3549..50b6876d 100644
--- a/core/hakmem_shared_pool.h
+++ b/core/hakmem_shared_pool.h
@@ -13,6 +13,62 @@
 extern "C" {
 #endif
 
+// ============================================================================
+// Phase 12: SP-SLOT Box - Per-Slot State Management
+// ============================================================================
+//
+// Problem:
+//   - Current design: 1 SuperSlab mixes multiple classes (C0-C7)
+//   - SuperSlab freed only when ALL classes empty (active_slabs==0)
+//   - Result: SuperSlabs rarely freed, LRU cache unused
+//
+// Solution:
+//   - Track each slab slot's state individually (UNUSED/ACTIVE/EMPTY)
+//   - Maintain per-class free slot lists for reuse
+//   - Free SuperSlab only when ALL slots empty
+//
+// Benefits:
+//   - Empty slabs from one class can be reused by same class immediately
+//   - Reduces mmap/munmap churn significantly
+//   - Enables LRU cache for fully empty SuperSlabs
+
+// Slot state for each (SuperSlab, slab_idx) pair
+typedef enum {
+    SLOT_UNUSED = 0,  // Never used yet
+    SLOT_ACTIVE,      // Assigned to a class (meta->used > 0 or freelist non-empty)
+    SLOT_EMPTY        // Was assigned, now empty (meta->used==0, remote==0)
+} SlotState;
+
+// Per-slot metadata
+typedef struct {
+    SlotState state;
+    uint8_t   class_idx;  // Valid when state != SLOT_UNUSED (0-7)
+    uint8_t   slab_idx;   // SuperSlab-internal index (0-31)
+} SharedSlot;
+
+// Per-SuperSlab metadata for slot management
+#define MAX_SLOTS_PER_SS 32  // Typical: 1MB SS has 32 slabs of 32KB each
+typedef struct SharedSSMeta {
+    SuperSlab*  ss;                          // Physical SuperSlab pointer
+    SharedSlot  slots[MAX_SLOTS_PER_SS];     // Slot state for each slab
+    uint8_t     active_slots;                // Number of SLOT_ACTIVE slots
+    uint8_t     total_slots;                 // Total available slots (from ss_slabs_capacity)
+    struct SharedSSMeta* next;               // For free list linking
+} SharedSSMeta;
+
+// Free slot entry for per-class reuse lists
+typedef struct {
+    SharedSSMeta* meta;   // Which SuperSlab metadata
+    uint8_t       slot_idx;  // Which slot within that SuperSlab
+} FreeSlotEntry;
+
+// Per-class free slot list (max capacity for now: 256 entries per class)
+#define MAX_FREE_SLOTS_PER_CLASS 256
+typedef struct {
+    FreeSlotEntry entries[MAX_FREE_SLOTS_PER_CLASS];
+    uint32_t      count;  // Number of free slots available
+} FreeSlotList;
+
 typedef struct SharedSuperSlabPool {
     SuperSlab** slabs;          // Dynamic array of SuperSlab*
     uint32_t    capacity;       // Allocated entries in slabs[]
@@ -29,6 +85,15 @@ typedef struct SharedSuperSlabPool {
     SuperSlab*  lru_head;
     SuperSlab*  lru_tail;
     uint32_t    lru_count;
+
+    // ========== Phase 12: SP-SLOT Management ==========
+    // Per-class free slot lists for efficient reuse
+    FreeSlotList free_slots[TINY_NUM_CLASSES_SS];
+
+    // SharedSSMeta array for all SuperSlabs in pool
+    SharedSSMeta* ss_metadata;    // Dynamic array
+    uint32_t      ss_meta_capacity;  // Allocated entries
+    uint32_t      ss_meta_count;     // Used entries
 } SharedSuperSlabPool;
 
 // Global singleton