hakmem/core/hakmem_policy.h

#ifndef HAKMEM_POLICY_H
#define HAKMEM_POLICY_H

#include <stddef.h>
#include <stdint.h>
#include <stdatomic.h>

#ifndef MAX_SITES
#define MAX_SITES 256
#endif

// FrozenPolicy: read-only snapshot used by the hot path.
// SACS-3: Only L1 (ACE layer) fields are consulted on the hot path.
typedef struct FrozenPolicy {
    // Tiny (L0) – reserved for future CAP tuning (not used by hot path yet)
    uint16_t tiny_cap[8];  // classes 0..7

    // L1 ACE – MidPool (2–32KiB) and LargePool (64KiB–1MiB)
    uint16_t mid_cap[5];    // 2/4/8/16/32 KiB
    uint16_t large_cap[5];  // 64/128/256/512 KiB/1 MiB
    uint32_t mid_dyn1_bytes; // Optional dynamic Mid class #1 (0=disabled)
    uint16_t mid_cap_dyn1;   // CAP for dynamic Mid class #1 (pages). 0=ignore
    uint32_t mid_dyn2_bytes; // Optional dynamic Mid class #2 (0=disabled)
    uint16_t mid_cap_dyn2;   // CAP for dynamic Mid class #2 (pages). 0=ignore

    // Optional: site/class routing within L1 (lightweight hints)
    uint8_t shard_map[MAX_SITES][10];   // (site,class)→shard id (0..N-1)
    uint8_t policy_map[MAX_SITES][10];  // (site,class)→policy (KEEP/WARM/COLD) hint

    // Limits
    // Max widening factor for class promotion (round-up policy)
    float    w_max_mid;      // MidPool (2–32KiB)
    float    w_max_large;    // LargePool (64KiB–1MiB)
    float    w_max;          // legacy (kept for compatibility)
    size_t   thp_threshold;  // L2 THP threshold (usually 2MiB)

    // Meta
    uint64_t generation;
} FrozenPolicy;

// Initialize default frozen policy.
void hkm_policy_init(void);

// Publish a new policy snapshot (RCU-like). Takes ownership of new_pol.
void hkm_policy_publish(FrozenPolicy* new_pol);

// Get the current policy snapshot (never NULL after init).
const FrozenPolicy* hkm_policy_get(void);

#endif // HAKMEM_POLICY_H