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 underlying JSVM that the VM system memory is insufficient and selectively trigger 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// Define OH_JSVM_AdjustExternalMemory.
34static JSVM_Value AdjustExternalMemory(JSVM_Env env, JSVM_CallbackInfo info)
35{
36    // Allocate 1 MB of memory.
37    int64_t change = 1024 * 1024;
38    int64_t adjustedValue = 0;
39    JSVM_Status status = OH_JSVM_AdjustExternalMemory(env, change, &adjustedValue);
40    if (status != JSVM_OK) {
41        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_AdjustExternalMemory: failed");
42    } else {
43        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_AdjustExternalMemory: success");
44        OH_LOG_INFO(LOG_APP, "JSVM Allocate memory size: %{public}d", adjustedValue);
45    }
46    JSVM_Value checked;
47    OH_JSVM_GetBoolean(env, true, &checked);
48    return checked;
49}
50// Register the AdjustExternalMemory callback.
51static JSVM_CallbackStruct param[] = {
52    {.data = nullptr, .callback = AdjustExternalMemory},
53};
54static JSVM_CallbackStruct *method = param;
55// Set a property descriptor named adjustExternalMemory and associate it with a callback. This allows the AdjustExternalMemory callback to be called from JS.
56static JSVM_PropertyDescriptor descriptor[] = {
57    {"adjustExternalMemory", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
58};
59```
60
61// Call the C++ code from JS.
62
63```c++
64const char *srcCallNative = R"JS(adjustExternalMemory())JS";
65```
66**Expected result**
67The following information is displayed in the log:
68JSVM OH_JSVM_AdjustExternalMemory: success
69JSVM Allocate memory size: 1048576
70
71### OH_JSVM_MemoryPressureNotification
72
73Use **OH_JSVM_MemoryPressureNotification** to notify the underlying JSVM that the VM system memory is insufficient and selectively trigger GC.
74
75CPP code:
76
77```cpp
78// hello.cpp
79#include "napi/native_api.h"
80#include "ark_runtime/jsvm.h"
81#include <hilog/log.h>
82// Define OH_JSVM_MemoryPressureNotification.
83static JSVM_Value MemoryPressureNotification(JSVM_Env env, JSVM_CallbackInfo info)
84{
85    // Set the memory pressure level of the current JSVM.
86    JSVM_Status status = OH_JSVM_MemoryPressureNotification(env, JSVM_MEMORY_PRESSURE_LEVEL_CRITICAL);
87    if (status != JSVM_OK) {
88        OH_LOG_ERROR(LOG_APP, "JSVM OH_JSVM_MemoryPressureNotification: failed");
89    } else {
90        OH_LOG_INFO(LOG_APP, "JSVM OH_JSVM_MemoryPressureNotification: success");
91        OH_LOG_INFO(LOG_APP, "JSVM Current JSVM memory pressure level: %{public}d", JSVM_MEMORY_PRESSURE_LEVEL_CRITICAL);
92    }
93    return nullptr;
94}
95// Register the MemoryPressureNotification callback.
96static JSVM_CallbackStruct param[] = {
97    {.data = nullptr, .callback = MemoryPressureNotification},
98};
99static JSVM_CallbackStruct *method = param;
100// Set a property descriptor named memoryPressureNotification and associate it with a callback. This allows the MemoryPressureNotification callback to be called from JS.
101static JSVM_PropertyDescriptor descriptor[] = {
102    {"memoryPressureNotification", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
103};
104```
105
106// Call the C++ code from JS.
107
108```c++
109const char *srcCallNative = R"JS(memoryPressureNotification())JS";
110```
111**Expected result**
112The following information is displayed in the log:
113JSVM OH_JSVM_MemoryPressureNotification: success
114JSVM Current JSVM memory pressure level: 2
115