/* play/mem_watch.h — 边播边监控**取证**（agent 32bit 大文件 OOM 取证；OOM_PAGECACHE_GOVERNANCE）。
 *
 * 归属演进（2026-09-02 定案，ARCHITECTURE_PRINCIPLES ③混合）：**降载决策上收通用层**——
 *   A（DONTNEED 治理）+ C（/proc/meminfo Cached 监控）分别归 SDK meow_cachegov / 系统服务
 *   meow_svc_perf；本模块退化为「RssAnon 取样取证」：一个轻量线程（ncm_thread_create 同款
 *   128KB 栈）低频（默认 500ms）读 /proc/self/status 的 RssAnon（缺失回退 VmRSS），记录匿名
 *   内存峰值（RssAnon 贴近「应用自有不可回收内存」，是 OOM kill 高危口径），**仅供日志/取证**，
 *   不再驱动下载/预取降载（那由 meow_cachegov_download_paused/prefetch_paused 查询）。
 *
 * 调度器结合释放钩子：mem_watch_song_begin/end 在 run_song 的起播/收尾（song_src_dispose +
 * ncm_dec_close + audio_out_close，即「彻底释放」钩子）处调用，重置本曲峰值计数并落日志
 * （峰值 RSS 即 RssAnon/RssFile 分离取证锚点；Cached/Dirty 侧取证归 svc_perf/meow_cachegov）。
 *
 * 阈值/开关可通过环境变量覆盖（宿主单测确定性驱动）：NCM_MEM_WATCH_ENABLED /
 * NCM_MEM_WATCH_PERIOD_MS / NCM_MEM_WATCH_HIGH_KB / NCM_MEM_WATCH_LOW_KB / NCM_MEM_WATCH_CRITICAL_KB。
 * 宿主测试桩：mem_watch_set_forced_kb() 注入读值（>=0 时监控线程不再读真 proc，仅测取证逻辑）。
 */
#ifndef NCM_MEM_WATCH_H
#define NCM_MEM_WATCH_H

#ifdef __cplusplus
extern "C" {
#endif

/* 内存压力档（仅取证日志用；不再驱动降载） */
enum {
    NCM_MEM_LVL_NORMAL   = 0,   /* < HIGH */
    NCM_MEM_LVL_HIGH     = 1,   /* ≥ HIGH */
    NCM_MEM_LVL_CRITICAL = 2,   /* ≥ CRITICAL */
};

/* 启动监控线程（幂等；ncm_thread_create 128KB 栈）。返回 0=ok / -1=线程建失败。 */
int  mem_watch_start(void);
/* 停止（置退出标志；线程 detach，不 join——同 ipc_media 模式）。 */
void mem_watch_stop(void);

/* 当前压力档（0/1/2；仅取证日志）。 */
int  mem_watch_level(void);
/* 最近一次采样的匿名 RSS（KB）；-1=不可读。 */
long mem_watch_rss_anon_kb(void);

/* ---- 调度器：与播放释放钩子联动 ---- */
/* 起播一首曲时调用：本曲峰值计数清零，开始记录本曲内存画像。 */
void mem_watch_song_begin(void);
/* 播完/切歌、即「彻底释放」钩子（decoder 关+下载线程 join+源关+.part 收尾）执行后调用：
 * 落本曲峰值日志 + 重置计数，给下一首让出统计（内存本身已由释放钩子归还）。 */
void mem_watch_song_end(void);

/* ---- 宿主测试桩（设备永不调用；≥0 时监控线程用注入值替代真 /proc 读）---- */
void mem_watch_set_forced_kb(long kb);

#ifdef __cplusplus
}
#endif
#endif /* NCM_MEM_WATCH_H */