/*
 * meow_cachegov.h — 磁盘缓存 page-cache 治理 SDK 库（A 的主导/治本侧）。
 *
 * 归属（devdocs/plan/ARCHITECTURE_PRINCIPLES.md ③混合，2026-09-02 用户定案）：
 *   - A（DONTNEED 热路径，需要 read_pos）    → 随 SDK 库（本文件，进程内直读 read_pos，无 IPC）。
 *   - C（设备级 /proc/meminfo Cached 监控降载）→ 归系统服务 meow_svc_perf；本模块只读其共享状态
 *     文件（MEOW_CACHEGOV_C_FILE）作为「降载」信号，供 App 查询。
 *   - App（如 ncm）侧只调本库接口：登记文件 + read_pos 回调 + tick + drop_finished + 查询降载，
 *     不写自己的治理算法。
 *
 * 权威方案：devdocs/plan/OOM_PAGECACHE_GOVERNANCE.md。红线：**L2（丢 read_pos 前方）禁止**，
 * 本库绝不 drop `[read_pos, ...)` 任何未解码区。
 *
 * 分级（§2.2）：
 *   L0（默认，安全）: 曲终/commit 后对整文件 posix_fadvise(DONTNEED)——播放器已退出解码循环。
 *   L1（可选，主杠杆）: 播放中丢已读前缀 `[0, read_pos-keep_hot)`，保 keep_hot 窗口供倒带；
 *                      仅 drop_mode>=1 且 A 未回退到 ≥2 时执行。
 *   L2（禁止，红线）: 绝不丢 read_pos 前方/当前未解码页。
 *
 * underrun 回退（§2.3，SDK 内置）：App 在 pread 慢（数据在盘上但 >threshold ms）处上报
 * meow_cachegov_note_refault()；本库滚窗 10s，超门限逐级回退（放大 keep_hot → 降 L0 → 关 A）。
 *
 * 接口按 OOM 文档 §4.2 + §4.4；值语义与 mem_watch 的「滞回三档」风格对齐（自含：pthread + meow_log）。
 */
#ifndef MEOW_CACHEGOV_H
#define MEOW_CACHEGOV_H

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

#ifdef __cplusplus
extern "C" {
#endif

typedef struct meow_cachegov_cfg {
    int    enabled;                /* 总开关：0=A 完全不丢页（register/tick/drop_finished 全部 no-op） */
    int    cached_threshold_kb;    /* 保留：C 侧阈值归 svc_perf（本库恒 0，只读不控，防误用） */
    int    dirty_warn_kb;          /* 保留：同上（svc_perf 用；本库只透传日志） */
    size_t keep_hot_bytes;         /* L1 保留窗口：read_pos 之后保多少不丢（回退时自动放大） */
    size_t min_hot_ahead;          /* L2 红线：read_pos 前方至少保多少——仅防御注释，**绝不参与 drop** */
    int    drop_mode;              /* 0=仅曲终(L0)；1=曲终+播放中丢已读前缀(L0+L1，配 seek 回退) */
    int    refault_backoff;        /* 10s 窗口内 refault 触发回退的门限（次数） */
} meow_cachegov_cfg_t;

/* 登记本次治理的缓存文件（正式缓存文件路径 + 大小 + read_pos 回调 + 回调 ctx）。
 * 返回 0=ok / 负=错。重复 path 幂等（替换条目）。 */
int meow_cachegov_register(const char *path, uint64_t size,
                           uint64_t (*read_pos_fn)(void *ctx), void *ctx);

/* 注销该 path 的治理条目（曲终/切歌后清理）。返回 0=找到并删 / 负=不在册。 */
int meow_cachegov_unregister(const char *path);

/* 周期调用（播放循环节拍 / 监控线程均可）：
 *   ① 按回退档执行 L1 丢弃（丢已读前缀 [0, read_pos-keep_hot)）；
 *   ② 评估 refault 滚窗做逐级回退。 */
int meow_cachegov_tick(void);

/* 曲终/commit 后：对刚播完文件做整文件 L0 DONTNEED + 注销该条目。
 * 回退档>=3（A 整体关闭）时不丢页（L0 也被关，见 §2.3 步骤 3）。 */
int meow_cachegov_drop_finished(const char *path);

/* 下载/预取方查询（1=应暂停）。数据源 = A 侧回退硬暂停 OR svc_perf C（Cached 超阈值）降载。 */
int meow_cachegov_download_paused(void);
int meow_cachegov_prefetch_paused(void);

/* 设置/读取治理配置（运行时覆盖编译期默认）。 */
int meow_cachegov_set_cfg(const meow_cachegov_cfg_t *cfg);
int meow_cachegov_get_cfg(meow_cachegov_cfg_t *cfg);

/* ---- refault 上报 + A 回退状态（underrun 检测，§2.3）---- */
/* App 在 pread 慢（数据已在盘上、读出 >threshold ms）处上报一次 refault。线程安全。 */
void meow_cachegov_note_refault(void);
/* A 当前回退档：0=正常 1=keep_hot 放大 2=降 L0（L1 关） 3=A 关。 */
int  meow_cachegov_backoff_level(void);

/* ---- 宿主测试桩（设备永不调用；-1=真实时钟，>=0 时用注入值替代 monotonic 时钟）---- */
void meow_cachegov_test_set_time_ms(int64_t t);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_CACHEGOV_H */