// ss_cache_box.h - SuperSlab Cache Management Box
// Purpose: LRU cache and prewarm/precharge cache for SuperSlab reuse
// Box Theory: Lazy deallocation strategy to minimize mmap/munmap syscalls
//
// Responsibilities:
//   - Per-class SuperSlab cache (prewarm/precharge)
//   - Cache initialization and configuration
//   - Runtime tuning API (learner integration)
//   - Cache hit/miss statistics
//
// Dependencies: ss_os_acquire_box (for precharge allocation)
//
// License: MIT
// Date: 2025-11-19

#ifndef HAKMEM_SS_CACHE_BOX_H
#define HAKMEM_SS_CACHE_BOX_H

#include <stdint.h>
#include <stddef.h>
#include "../superslab/superslab_types.h"

// ============================================================================
// Cache Statistics (external visibility for monitoring)
// ============================================================================

extern uint64_t g_ss_cache_hits[8];       // Cache hits per class
extern uint64_t g_ss_cache_misses[8];     // Cache misses per class
extern uint64_t g_ss_cache_puts[8];       // Cache stores per class
extern uint64_t g_ss_cache_drops[8];      // Cache evictions per class
extern uint64_t g_ss_cache_precharged[8]; // Precharge count per class

// ============================================================================
// Cache Management API
// ============================================================================

// Initialize cache system (called once per process)
// Thread-safe: pthread_once protected
void ss_cache_ensure_init(void);

// Pop SuperSlab from cache (returns NULL if cache empty)
// Thread-safe: mutex protected
// Returns: SuperSlab pointer (cast from SuperslabCacheEntry) or NULL
void* ss_cache_pop(uint8_t size_class);

// Push SuperSlab to cache (for lazy deallocation)
// Thread-safe: mutex protected
// Returns: 1 if cached, 0 if cache full (caller should munmap)
int ss_cache_push(uint8_t size_class, SuperSlab* ss);

// Precharge cache with N SuperSlabs (startup optimization)
// Thread-safe: mutex protected, one-shot per class
// Populates cache to reduce first-allocation latency
void ss_cache_precharge(uint8_t size_class, size_t ss_size, uintptr_t ss_mask);

// Cache capacity and precharge target arrays (for direct access from allocation box)
extern size_t g_ss_cache_cap[8];
extern size_t g_ss_precharge_target[8];

// ============================================================================
// Runtime Tuning API (Learner Integration)
// ============================================================================

// Set per-class cache capacity (runtime tunable)
// If new_cap < old_cap, excess cached SuperSlabs are munmapped
// Thread-safe: mutex protected
//
// Parameters:
//   class_idx: Tiny class (0..7)
//   new_cap: Maximum cached SuperSlabs for this class (0 = disable cache)
//
// Used by: TinyPageAuto learner for adaptive cache sizing
void tiny_ss_cache_set_class_cap(int class_idx, size_t new_cap);

// Set per-class precharge target (runtime tunable)
// If target > 0, precharge will run on next allocation
// Thread-safe: mutex protected
//
// Parameters:
//   class_idx: Tiny class (0..7)
//   target: Number of SuperSlabs to precharge (0 = disable precharge)
//
// Used by: TinyPageAuto learner based on PageFaultTelemetry
void tiny_ss_precharge_set_class_target(int class_idx, size_t target);

#endif // HAKMEM_SS_CACHE_BOX_H