hakmem/core/hakmem_whale.h

// hakmem_whale.h - Whale Fast-Path (Box理論: クジラ箱)
// Purpose: FIFO ring cache for ≥2MB allocations to avoid munmap overhead
//
// Design:
// - FIFO eviction (oldest block evicted first)
// - O(1) get/put operations
// - Fixed capacity (8 slots = 16MB cache)
// - Size: ≥2MB blocks only (whale threshold)
//
// Expected Impact: -6000-9000ns per operation (eliminates 96.3% munmap overhead)
//
// License: MIT
// Date: 2025-10-21

#pragma once
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Configuration
// ============================================================================

#define WHALE_MIN_SIZE      (2 * 1024 * 1024)   // 2MB threshold
#define WHALE_RING_CAPACITY 8                   // 8 slots = 16MB cache

// ============================================================================
// Public API
// ============================================================================

// Initialize whale cache (called from hak_init)
void hkm_whale_init(void);

// Shutdown whale cache (called from hak_shutdown)
void hkm_whale_shutdown(void);

// Try to get a whale block from cache (O(1))
// Args: size - requested size (must be >= WHALE_MIN_SIZE)
// Returns: Cached block pointer, or NULL if cache miss
void* hkm_whale_get(size_t size);

// Put a whale block back into cache (O(1))
// Args: ptr - block pointer (from hkm_sys_mmap)
//       size - block size
// Returns: 0 if cached, 1 if cache full (caller should munmap)
int hkm_whale_put(void* ptr, size_t size);

// Dump statistics (called at shutdown)
void hkm_whale_dump_stats(void);

#ifdef __cplusplus
}
#endif