• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Performing Memory Management Using JSVM-API
2
3## Introduction
4
5JSVM-API provides APIs for managing JavaScript virtual machine (JSVM) memory. With these APIs, you can better control the memory used by JS code and optimize memory management and garbage collection (GC) mechanisms.
6
7## Basic Concepts
8
9In JS, memory management and GC are performed automatically. The JSVM is responsible for tracking the allocation and release of objects and reclaiming the memory that is no longer required. However, if a JSVM consumes a large amount of memory, an out-of-memory error may occur. To prevent this type of errors, JSVM-API provides APIs to better control memory management and GC mechanisms.
10
11## Available APIs
12
13| API                      | Description                           |
14|----------------------------|-------------------------------------|
15| OH_JSVM_AdjustExternalMemory         | Manages the external allocated memory held by a JS object.|
16| OH_JSVM_MemoryPressureNotification   | Notifies the VM of the memory pressure level and selectively triggers GC.|
17
18## Example
19
20If you are just starting out with JSVM-API, see [JSVM-API Development Process](use-jsvm-process.md). The following demonstrates only the C++ and ArkTS code related to memory management.
21
22### OH_JSVM_AdjustExternalMemory
23
24Use **OH_JSVM_AdjustExternalMemory** to adjust the amount of externally allocated memory that is kept alive for a JS object.
25
26CPP code:
27
28```cpp
29// hello.cpp
30#include "napi/native_api.h"
31#include "ark_runtime/jsvm.h"
32#include <hilog/log.h>
33// Register the AdjustExternalMemory callback.
34static JSVM_CallbackStruct param[] = {
35    {.data = nullptr, .callback = AdjustExternalMemory},
36};
37static JSVM_CallbackStruct *method = param;
38// Set a property descriptor named adjustExternalMemory and associate it with a callback. This allows the AdjustExternalMemory callback to be called from JS.
39static JSVM_PropertyDescriptor descriptor[] = {
40    {"adjustExternalMemory", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
41};
42// Define OH_JSVM_AdjustExternalMemory.
43static JSVM_Value AdjustExternalMemory(JSVM_Env env, JSVM_CallbackInfo info)
44{
45    // Allocate 1 MB of memory.
46    int64_t change = 1024 * 1024;
47    int64_t adjustedValue = 0;
48    JSVM_Status status = OH_JSVM_AdjustExternalMemory(env, change, &adjustedValue);
49    if (status != JSVM_OK) {
50        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_AdjustExternalMemory: failed");
51    } else {
52        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_AdjustExternalMemory: success");
53        OH_LOG_INFO(LOG_APP, "JSVM Allocate memory size: %{public}d", adjustedValue);
54    }
55    JSVM_Value checked;
56    OH_JSVM_GetBoolean(env, true, &checked);
57    return checked;
58}
59```
60
61ArkTS code:
62
63```ts
64import hilog from "@ohos.hilog"
65// Import the native APIs.
66import napitest from "libentry.so"
67let script: string = `
68   adjustExternalMemory()
69  `;
70try {
71  let result = napitest.runJsVm(script);
72  hilog.info(0x0000, 'JSVM', 'adjustExternalMemory:%{public}s', result);
73} catch (error) {
74  hilog.error(0x0000, 'JSVM', 'adjustExternalMemory: %{public}s', error.message);
75}
76```
77
78### OH_JSVM_MemoryPressureNotification
79
80Use **OH_JSVM_MemoryPressureNotification** to notify the underlying JSVM that the VM system memory is insufficient and selectively trigger GC.
81
82CPP code:
83
84```cpp
85// hello.cpp
86#include "napi/native_api.h"
87#include "ark_runtime/jsvm.h"
88#include <hilog/log.h>
89// Register the MemoryPressureNotification callback.
90static JSVM_CallbackStruct param[] = {
91    {.data = nullptr, .callback = MemoryPressureNotification},
92};
93static JSVM_CallbackStruct *method = param;
94// Set a property descriptor named memoryPressureNotification and associate it with a callback. This allows the MemoryPressureNotification callback to be called from JS.
95static JSVM_PropertyDescriptor descriptor[] = {
96    {"memoryPressureNotification", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
97};
98// Define OH_JSVM_MemoryPressureNotification.
99static JSVM_Value MemoryPressureNotification(JSVM_Env env, JSVM_CallbackInfo info)
100{
101    // Set the memory pressure level of the current JSVM.
102    JSVM_Status status = OH_JSVM_MemoryPressureNotification(env, JSVM_MEMORY_PRESSURE_LEVEL_CRITICAL);
103    if (status != JSVM_OK) {
104        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_MemoryPressureNotification: failed");
105    } else {
106        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_MemoryPressureNotification: success");
107        OH_LOG_INFO(LOG_APP, "JSVM Current JSVM memory pressure level: %{public}d", JSVM_MEMORY_PRESSURE_LEVEL_CRITICAL);
108    }
109    return nullptr;
110}
111```
112
113ArkTS code:
114
115```ts
116import hilog from "@ohos.hilog"
117// Import the native APIs.
118import napitest from "libentry.so"
119let script: string = `
120   memoryPressureNotification();
121  `;
122try {
123  let result = napitest.runJsVm(script);
124  hilog.info(0x0000, 'JSVM', 'memoryPressureNotification:%{public}s', result);
125} catch (error) {
126  hilog.error(0x0000, 'JSVM', 'memoryPressureNotification:%{public}s', error.message);
127}
128```
129