高内存事件
从 Lynx 4.5 开始,宿主可以注册进程级回调,接收共享后台 VM、页面后台 runtime 和页面 UI 内存的高内存事件,用于定位占用较大的 VM 或页面实例,并决定是否进一步采集诊断信息。
SDK 将事件以字典形式交给宿主。数据上报与后续处理由宿主负责,回调本身不会释放内存。
注册回调
建议在应用初始化时尽早注册。回调会被全局持有,并在主线程/UI 线程异步执行。回调内应只做轻量处理,将耗时分析或上传转移到其他线程。
Android
回调接口为 LynxEnv.HighMemoryCallback,方法为 onHighMemoryEvent(Map<String, Object> event)。
iOS
HarmonyOS
HarmonyOS 中的数值字段均为 number,slots 类型为 Array<LynxHighMemorySlot>,counts 类型为 Array<string | number>。
原生嵌入环境
C API 接收回调及不透明的用户数据指针:
应在 UI 线程注册或清除回调。传入空回调会清除全部注册项。C++ 入口为 LynxEnv::GetInstance().SetHighMemoryCallback(callback, user_data)。
C 回调接收的值为借用值,只在回调返回前有效。如需留到后续处理,可在 C++ 中通过 lynx_value_add_reference(nullptr, *event, nullptr) 保留引用,或使用持有所有权的 pub::LynxValue。
配置采样率与阈值
宿主设置方式、初始化时机、采样率、默认值和高内存回调配置示例见内存监控配置。通过 memory_monitor_config 设置 large_vm_threshold_mb、large_bts_threshold_mb 和 large_ui_threshold_mb。
阈值单位为 MiB,0 禁用对应事件类型。测量字节数大于或等于配置阈值时,事件满足触发条件。
large_bts 和 large_ui 需要启用内存监控,large_ui 还需要启用 UI 采集。即使未启用内存监控,共享 QuickJS VM 仍可通过已有 GC 通知触发 large_vm。
事件字段
每次回调接收一个事件字典。不适用于当前事件类型的字段会被省略。
共享 VM 事件
large_vm 表示共享后台 VM 的堆大小。对于共享 QuickJS VM,可通过 slots 查看页面和共享分配对堆内存的贡献:
共享 QuickJS VM 通过已有 GC 通知检查阈值;V8 和 JSVM 在启用监控且成功刷新堆大小后检查。独立 VM 不触发 large_vm,JSC 不支持堆大小采集。回调机制不会新增 GC 或分配通知。
页面后台 Runtime 事件
large_bts 表示归因到存活页面的后台 runtime 内存。对于共享 QuickJS VM,该值为页面的 slot 分量;对于独立 VM,该值为页面所用 VM 的整体堆大小。
示例表示实例 204 的后台 runtime 内存为 576 MiB。应结合 instance_id 与 key 区分同一页面的并发实例或重新加载后创建的实例。
页面 UI 事件
large_ui 表示存活页面的 UI 内存,其 bytes 不包含 Element tree 和 runtime 内存。
示例表示 UI 内存为 80 MiB。counts 返回缓存的分类对象数量,可能包含脚本引擎或 lynxTasmElement 等非 UI 分类。它是诊断上下文,不是对 bytes 的字节数拆分。
触发与生命周期
- 每次注册非空回调都会追加监听。传入
null、nil或undefined会清除所有监听。监听按注册顺序执行;全局持有的回调应避免捕获页面对象。 - 每个 VM 最多触发一次
large_vm,每个页面最多分别触发一次large_bts和large_ui。内存降到阈值以下或页面 reload 都不会重置触发标记。 - 即使没有注册监听,达到阈值的事件也会消耗一次性触发标记。之后注册回调不会补发历史事件。
- UI 投递任务开始执行时会复制监听列表。在回调内追加或清除监听,只影响后续投递。
- 页面阈值检查在内存刷新及共享 VM 归因后执行,并跳过已退出页面。由内存数据更新驱动的刷新使用
60秒间隔,tracing 期间为16ms;其他刷新可能重置该间隔。该功能不会新增轮询定时器,因此回调不会即时通知每次阈值跨越。
排查高内存
收到 large_vm 时,可以检查 slots,并将实例 ID 与宿主的页面生命周期记录对照。Slot 可能对应仍有归因内存的已退出页面,这意味着需要排查对象保活,但不能直接证明内存泄漏。total_page_count 只应用作生命周期背景信息。
收到页面事件时,应将 key 和 instance_id 与页面加载、reload 和销毁记录关联。根据 vm_type 选择适用的 runtime 诊断方式;收到 large_ui 时可进一步检查 UI 对象数量。
可以通过全局 Lynx 内存查询获取当前进程的内存清单。Lynx 4.5 中,关闭监控时也可查询,但页面 BTS 归因、UI 内存和已销毁页面残留仍需要监控,应先检查 memoryMonitoringEnabled 再解读这些字段。高内存事件用于定位达到阈值的对象,全局查询或 heap snapshot 则提供进一步诊断所需的证据。
排查 QuickJS runtime 对象保活时,参见堆快照采集。存活页面分量使用 bts_page,后台 VM 整体堆使用 bts_vm;slot 的 instance_id 对应已销毁页面时,可在共享 VM 仍存活的前提下使用静态 takeBtsResidualHeapSnapshot 接口。