High Memory Events
Starting in Lynx 4.5, a host app can register a process-wide callback to receive high-memory events for shared background VMs, page background runtimes, and page UI memory. Use these events to identify large VMs or page instances and decide whether to collect further diagnostics.
The SDK delivers a dictionary to the host. The host is responsible for uploading analytics or taking action; the callback does not release memory.
Register A Callback
Register early during app initialization. Callbacks are retained globally and delivered asynchronously on the main/UI thread. Keep callback work short and move expensive processing or uploads off that thread.
Android
The callback interface is LynxEnv.HighMemoryCallback, with the method onHighMemoryEvent(Map<String, Object> event).
iOS
HarmonyOS
HarmonyOS exposes numeric fields as number, slots as Array<LynxHighMemorySlot>, and counts as Array<string | number>.
Native Embedders
The C API accepts a callback and an opaque user-data pointer:
Register and clear callbacks on the UI thread. Passing a null callback clears all registrations. The C++ entry point is LynxEnv::GetInstance().SetHighMemoryCallback(callback, user_data).
The C callback receives a borrowed value that is valid until the callback returns. To keep the event for later processing, retain it with lynx_value_add_reference(nullptr, *event, nullptr) in C++, or use an owning pub::LynxValue.
Configure Sampling And Thresholds
See Memory Monitor Configuration for host configuration, initialization timing, sampling rates, defaults, and a high-memory callback configuration example. Set large_vm_threshold_mb, large_bts_threshold_mb, and large_ui_threshold_mb through memory_monitor_config.
The thresholds use MiB, and 0 disables the corresponding event type. An event is eligible when the measured bytes are greater than or equal to the configured threshold.
large_bts and large_ui require enabled memory monitoring; large_ui also requires UI collection. Shared QuickJS VMs can still emit large_vm from existing GC notifications when memory monitoring is disabled.
Event Fields
Each callback receives one event dictionary. Fields that do not apply to its event type are omitted.
Shared VM Event
large_vm reports the heap size of a shared background VM. For shared QuickJS, slots helps identify the pages and shared allocations contributing to that heap:
Shared QuickJS VM checks run from existing GC notifications. V8 and JSVM checks run after a successful heap refresh while monitoring is enabled. Standalone VMs do not emit large_vm, and JSC heap collection is unsupported. The callback does not introduce additional GC or allocation notifications.
Page Background Runtime Event
large_bts reports background runtime memory attributed to a live page. For a shared QuickJS VM, this is the page's slot component; for a standalone VM, it is that page's VM heap size.
The example identifies instance 204 with 576 MiB of background runtime memory. Use instance_id with key to distinguish concurrent or reloaded instances of the same page.
Page UI Event
large_ui reports a live page's UI memory. Its bytes excludes Element tree and runtime memory.
The example reports 80 MiB of UI memory. counts contains cached category counts and can include non-UI categories, such as scripting engines or lynxTasmElement. It is diagnostic context, not a byte breakdown of bytes.
Delivery And Lifetime
- Each non-null callback registration appends a listener. Passing
null,nil, orundefinedclears all listeners. Listeners run in registration order; avoid capturing page objects in these globally retained callbacks. - Each VM emits
large_vmat most once. Each page emitslarge_btsandlarge_uiat most once each. Dropping below the threshold or reloading a page does not reset these flags. - A threshold event consumes its one-shot flag even when no listener is registered. Registering later does not replay past events.
- The listener list is copied when the UI delivery task starts. Adding or clearing listeners inside a callback affects later deliveries.
- Page checks run after memory refresh and shared-VM attribution, and skip exited pages. Refreshes driven by memory producer updates use a
60-second interval, or16ms while tracing; other refreshes can reset that interval. No additional polling timer is introduced, so the callback is not an immediate notification of every threshold crossing.
Diagnose High Memory
For large_vm, inspect slots and compare instance IDs with the host's page lifecycle records. A slot can refer to an exited page that still has attributed memory; this is a reason to investigate retention, not proof of a leak. Use total_page_count only as lifetime context.
For page events, correlate key and instance_id with page load, reload, and destruction records. Use vm_type to choose suitable runtime diagnostics, and inspect UI object counts when large_ui fires.
Use the global Lynx memory query to obtain a current process-wide inventory. In Lynx 4.5, it also works without monitoring, but page BTS attribution, UI memory, and destroyed-page residuals require monitoring; check memoryMonitoringEnabled before interpreting those fields. High-memory events identify threshold cases; a global query or heap snapshot supplies the additional evidence needed for diagnosis.
For QuickJS runtime retention, see Heap Snapshot Collection. Use bts_page for a live page's component or bts_vm for the whole background VM. For a destroyed page identified by a slot's instance_id, use the static takeBtsResidualHeapSnapshot API while its shared VM is still alive.