hakmem/core/hakmem.h

// hakmem.h - Minimal PoC for Call-site Profiling
// Purpose: Verify the core concept from the paper
//
// License: MIT
// Date: 2025-10-21

#pragma once
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include "hakmem_build_flags.h"

#ifdef __cplusplus
extern "C" {
#endif

// ============================================================================
// Call-site profiling (Core concept)
// ============================================================================

typedef const void* hak_callsite_t;

// Platform-specific call-site extraction
#if defined(__GNUC__) || defined(__clang__)
  #define HAK_CALLSITE() __builtin_return_address(0)
#elif defined(_MSC_VER)
  #include <intrin.h>
  #define HAK_CALLSITE() _ReturnAddress()
#else
  #define HAK_CALLSITE() NULL
#endif

// Low-level API (for PoC)
void* hak_alloc_at(size_t size, hak_callsite_t site);
void  hak_free_at(void* ptr, size_t size, hak_callsite_t site);

// Zero-friction macros (main API)
#define hak_alloc_cs(sz)    hak_alloc_at((sz), HAK_CALLSITE())
#define hak_free_cs(p, sz)  hak_free_at((p), (sz), HAK_CALLSITE())

// ============================================================================
// Profiling & Stats (for verification)
// ============================================================================

typedef struct {
    uintptr_t site_id;       // Call-site address
    uint64_t  alloc_count;   // Total allocations
    uint64_t  total_bytes;   // Total bytes allocated
    size_t    avg_size;      // Average allocation size
    size_t    max_size;      // Maximum size seen
} hak_site_stats_t;

// ============================================================================
// KPI Metrics (for UCB1 learning) - NEW!
// ============================================================================

typedef struct {
    // Latency (nanoseconds)
    uint64_t p50_alloc_ns;   // Median allocation latency
    uint64_t p95_alloc_ns;   // 95th percentile
    uint64_t p99_alloc_ns;   // 99th percentile

    // Page Faults (Linux /proc/self/stat)
    uint64_t soft_page_faults;   // Minor faults (no disk I/O)
    uint64_t hard_page_faults;   // Major faults (disk I/O)

    // Memory (from system)
    int64_t  rss_delta_mb;       // RSS change in MB (can be negative)
} hak_kpi_t;

// ============================================================================
// UCB1 Evolution (for learning) - NEW!
// ============================================================================

// Discrete policy steps for mmap_threshold
typedef enum {
    STEP_64KB = 0,
    STEP_128KB = 1,
    STEP_256KB = 2,
    STEP_512KB = 3,
    STEP_1MB = 4,
    STEP_2MB = 5,
    STEP_COUNT = 6  // Total number of steps
} MmapThresholdStep;

// UCB1 Evolution control
typedef struct {
    int enabled;                 // 0 = baseline, 1 = evolving
    uint64_t iteration_count;    // Total iterations
    uint64_t last_evolution_ms;  // Last evolution timestamp (ms)
} hak_evolution_control_t;

// Get profiling statistics for debugging
void hak_print_stats(void);

// NEW: Get current KPI metrics
void hak_get_kpi(hak_kpi_t* out);

// NEW: Evolution control
void hak_enable_evolution(int enable);  // 0 = baseline, 1 = evolving
void hak_trigger_evolution(void);       // Manually trigger evolution cycle
size_t hak_ucb1_get_threshold(void);    // Get current UCB1 threshold

// Initialize/cleanup
void hak_init(void);
void hak_shutdown(void);

// Recursion guard (true if inside malloc/free/realloc/calloc wrappers)
int hak_in_wrapper(void);
// Initialization guard (true while hak_init is running)
int hak_is_initializing(void);

#ifdef __cplusplus
}
#endif