memory_debug

启用与裁剪

定义 XRT_FEATURE_MEMORY_DEBUG 后，xrtMalloc、xrtCalloc、xrtRealloc、xrtFree 和 xrtMemDup 自动记录 __FILE__、__LINE__。未定义该宏时，调试块头、canary、事件、活动链表和隔离队列全部从构建中裁掉。

XRT_MODULE_ALL 默认包含内存调试。完整生产构建可以在首次包含 XRT 头之前定义 XRT_EXCLUDE_MEMORY_DEBUG，同时裁掉调试核心和报告层而保留 memory_stats。该排除 只影响 XRT_MODULE_ALL 的隐式选择；显式选择内存调试模块仍然优先。

文本和 JSON 报告由单独的 XRT_FEATURE_MEMORY_DEBUG_REPORT 控制。它依赖调试核心，但不依赖文件、字符串构建器或 JSON 模块；不需要报告时不会带入格式化代码。

调试构建默认开启运行时记录。运行时关闭只用于暂时停止统计，不会改变编译期内存布局或移除调试分配路径，不能代替 XRT_EXCLUDE_MEMORY_DEBUG。存在任何活动 XRT 分配时不能切换开关或重置状态。

故障注入同样只在调试构建存在。它按 xrtMalloc、xrtCalloc、非零 xrtRealloc 和 xrtMemDup 的逻辑调用计数，不受小对象池、线程缓存或 backing allocator 复用影响；状态属于当前线程，不会让并行任务随机失败。

检测范围

• 前后 canary 检测缓冲区下溢和溢出；释放时发现损坏会记录事件并设置 XERR_STATE。
• 池化块释放后填充 0xDD，复用前检测释放后写入。
• 大块释放后进入有界隔离队列，延迟归还底层分配器。
• 活动分配链表提供泄漏位置和大小。
• 临时 arena 记录分配、作用域回退、reset、当前字节和峰值字节。
• 非 XRT 地址先经过所有权查询，不盲目读取未知地址之前的内存。
• 事件历史固定保留最近 512 条，不因长时间运行无限增长。

并发调用是安全的。访问器在内部锁之外执行，可以正常输出日志；访问器收到的结构只在当前回调期间借用。

范例

完整范例位于 examples/memory/debug/main.c，并由 python tools/build.py --suite memory_debug 自动编译运行。

流式报告范例位于 examples/memory/debug_report/main.c，由 python tools/build.py --suite memory_debug_report 验证。

旧版资产决策

旧版 canary、512 条有界事件、256 块大对象隔离、分配点宏、文本/JSON 报告和临时 arena 事件均被保留并压实。报告从直接打开路径改为写入器分层，避免内存调试核心强依赖文件系统，也允许直接流向日志或网络。

旧版为每个容器 API 生成一组 Dbg 宏、在全局调试器中维护容器对象表的做法不再保留。分配点由统一内存宏覆盖；对象生命周期和错误状态由各对象模块自身的状态机负责，避免内存调试模块反向耦合全部容器。错误分配器释放仍由拥有该地址的分配器边界验证，通用堆把未知地址报告为 XERR_ARGUMENT。