lynx.performance.getMemoryUsage()
Starting in Lynx 4.4, background-thread JavaScript can use lynx.performance.getMemoryUsage(callback) to asynchronously query the current page instance's memory. The result includes Element memory, main-thread runtime (MTS) memory, the page's background runtime (BTS) component, the whole BTS VM heap, and UI memory.
The API returns a best-effort memory summary. It does not generate heap snapshot files or query other pages or destroyed-page residuals.
Monitoring Requirements
The host must enable memory monitoring through memory_monitor_config before creating pages or VMs, and the current process must be selected by global_sample_rate. Calling the JavaScript API does not enable monitoring.
To enable core memory collection in the target process, set:
To include UI memory, also enable UI collection:
A sampling rate below 1 does not guarantee that the process is selected. When monitoring is disabled or the process is not selected by global sampling, the callback returns MONITORING_DISABLED; the API does not collect memory from unmonitored pages on demand.
Syntax
The return value is void. Results arrive asynchronously through the callback; the API does not return a Promise. Passing an invalid callback throws an exception.
Example
Query Status
MemoryUsageQueryStatus defines these numeric statuses:
Read other fields only when status === 0. For other statuses, memory and count fields are 0 and btsShared is false; these defaults must not be consumed as page memory data.
Even with OK, unsupported, unavailable, or failed numeric sources can return 0. Except for status, consume numeric fields only when they are greater than 0; a zero value does not establish measured zero memory.
Result Fields
The callback receives a MemoryUsage object. Memory fields use bytes; count fields use object counts.
Shared QuickJS VM slots 0, 1, and 2 are reserved. A VM can assign independent attribution slots to at most 253 pages over its lifetime. Later pages using the shared overflow slot cannot report page-specific BTS components. This is not a limit on concurrently live pages.
Collection Semantics
- The API is exposed only to background-thread JavaScript. The callback returns asynchronously to the calling JS thread.
- A query aggregates existing page memory records and attempts to refresh the available whole BTS VM heap. Fields can come from different times and do not guarantee a complete, immediate measurement.
- A query does not trigger GC or release memory. Use it for on-demand diagnostics rather than frequent polling.
- If the page or JS runtime is destroyed before callback delivery, the callback may not run. Do not rely on the API to return a result after destruction.
Diagnose Memory Usage
Check status first, then compare available fields. When btsShared is true, interpret btsBytes and btsHeapBytes separately: do not attribute the whole shared VM heap to the current page or add it again to totalBytes. Keep monitoring and UI sampling settings consistent across comparisons.
Use the host-side global memory query to inspect other instances in the current process or destroyed-page residuals. To analyze JavaScript reference chains, see Heap Snapshot Collection.
Compatibility
LCD tables only load in the browser