// tiny_near_empty_box.h - Box: Tiny Near-Empty Slab Advisor (C2/C3)
//
// 目的:
//   - Tiny Superslab の free パスで「ほぼ空き slab」を検出する軽量な観測箱。
//   - いまは C2/C3 限定で、used/cap から near-empty な slab を検知して
//     カウンタを増やすだけ（SuperSlab/SharedPool の状態は一切変更しない）。
//   - Learner から near-empty 統計を見て CAP/キャッシュ/しきい値を調整する足場として使う。
//
// ENV:
//   - HAKMEM_TINY_SS_PACK_C23=1
//       → C2/C3 の near-empty 検出を有効化（既定0: 無効）。
//   - HAKMEM_TINY_NEAREMPTY_DUMP=1
//       → 終了時に [TINY_NEAR_EMPTY_STATS] を 1 回だけダンプ。
//   - HAKMEM_TINY_NEAREMPTY_PCT=P (1-99, default 25)
//       → near-empty 判定の使用率しきい値 (%).

#pragma once

#include <stdint.h>
#include "../hakmem_tiny_config.h"     // TINY_NUM_CLASSES
#include "../superslab/superslab_types.h"  // TinySlabMeta, SuperSlab

#ifdef __cplusplus
extern "C" {
#endif

// Per-class near-empty events（観測用カウンタ）
extern _Atomic uint64_t g_tiny_near_empty_events[TINY_NUM_CLASSES];

// 現在のしきい値（%）を取得（1-99）
int tiny_near_empty_get_pct(void);

// しきい値（%）を更新（1-99 範囲外の値は無視）
void tiny_near_empty_set_pct(int pct);

// near-empty 検出（free パスから呼ばれるメインエントリ）。
//   - C2/C3 限定（現時点では 32B〜128B のホットクラスのみ）。
//   - used>0 かつ used/cap <= THRESH_PCT% のとき near-empty とみなして 1 カウント。
//   - SuperSlab/SharedPool の state には触らない（観測のみ）。
static inline void tiny_near_empty_on_free(int class_idx,
                                           SuperSlab* ss,
                                           int slab_idx,
                                           TinySlabMeta* meta)
{
    (void)ss;
    (void)slab_idx;
    if (!meta) {
        return;
    }
    extern int tiny_near_empty_enabled(void);
    extern void tiny_near_empty_on_free_impl(int class_idx, TinySlabMeta* meta);
    if (!tiny_near_empty_enabled()) {
        return;
    }
    tiny_near_empty_on_free_impl(class_idx, meta);
}

// near-empty 統計のスナップショットを取得。
//   - events: 出力配列（NULL の場合は無視）
//   - reset!=0 のとき、読み取り後 0 にリセットする。
void tiny_near_empty_stats_snapshot(uint64_t events[TINY_NUM_CLASSES],
                                    int reset);

#ifdef __cplusplus
}
#endif