n-api: adds function to adjust external memory

Added a simple wrapper around v8::Isolate::AdjustAmountOfExternalAllocatedMemory Fixes: nodejs#13928
chris--young · Aug 25, 2017 · a785d8c · a785d8c
1 parent a1d34b3
commit a785d8c
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 0 deletions.
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
@@ -3394,6 +3394,27 @@ support it:
 * If the function is not available, provide an alternate implementation
   that does not use the function.
 
+### napi_adjust_external_memory
+<!-- YAML
+added: REPLACEME
+-->
+```C
+NAPI_EXTERN int64_t napi_adjust_external_memory(napi_env env,
+                                         int64_t change_in_bytes);
+```
+
+- `[in] env`: The environment that the API is invoked under.
+- `[in] change_in_bytes`: The change in externally allocated memory that is
+kept alive by JavaScript objects.
+
+Returns `int64_t` the adjusted value.
+
+This function gives V8 an indication of the amount of externally allocated 
+memory that is kept alive by JavaScript objects (i.e. a JavaScript object
+that points to its own memory allocated by a native module). Registering 
+externally allocated memory will trigger global garbage collections more 
+often than it would otherwise.
+
 <!-- it's very convenient to have all the anchors indexed -->
 <!--lint disable no-unused-definitions remark-lint-->
 ## Promises
@@ -3549,6 +3570,7 @@ object - that is, a promise object created by the underlying engine.
 [Working with JavaScript Values]: #n_api_working_with_javascript_values
 [Working with JavaScript Values - Abstract Operations]: #n_api_working_with_javascript_values_abstract_operations
 
+[`napi_adjust_external_memory`]: #n_api_napi_adjust_external_memory
 [`napi_cancel_async_work`]: #n_api_napi_cancel_async_work
 [`napi_close_escapable_handle_scope`]: #n_api_napi_close_escapable_handle_scope
 [`napi_close_handle_scope`]: #n_api_napi_close_handle_scope

diff --git a/src/node_api.cc b/src/node_api.cc
@@ -3213,6 +3213,19 @@ napi_status napi_get_node_version(napi_env env,
   return napi_clear_last_error(env);
 }
 
+napi_status napi_adjust_external_memory(napi_env env,
+                                        int64_t change_in_bytes,
+                                        int64_t* adjusted_value) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, &change_in_bytes);
+  CHECK_ARG(env, adjusted_value);
+
+  *adjusted_value = env->isolate->AdjustAmountOfExternalAllocatedMemory(
+      change_in_bytes);
+
+  return napi_clear_last_error(env);
+}
+
 namespace uvimpl {
 
 static napi_status ConvertUVErrorCode(int code) {

diff --git a/src/node_api.h b/src/node_api.h
@@ -557,6 +557,11 @@ NAPI_EXTERN napi_status napi_is_promise(napi_env env,
                                         napi_value promise,
                                         bool* is_promise);
 
+// Memory management
+NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env,
+                                                    int64_t change_in_bytes,
+                                                    int64_t* adjusted_value);
+
 EXTERN_C_END
 
 #endif  // SRC_NODE_API_H_
diff --git a/test/addons-napi/test_general/test.js b/test/addons-napi/test_general/test.js
@@ -91,3 +91,7 @@ z = null;
 global.gc();
 assert.strictEqual(test_general.finalizeWasCalled(), false,
                    'finalize callback was not called upon garbage collection');
+
+// test napi_adjust_external_memory
+const adjustedValue = test_general.testAdjustExternalMemory();
+assert.strictEqual(typeof adjustedValue, 'number');
diff --git a/test/addons-napi/test_general/test_general.c b/test/addons-napi/test_general/test_general.c
@@ -205,6 +205,16 @@ napi_value finalize_was_called(napi_env env, napi_callback_info info) {
   return it_was_called;
 }
 
+napi_value testAdjustExternalMemory(napi_env env, napi_callback_info info) {
+  napi_value result;
+  int64_t adjustedValue;
+
+  NAPI_CALL(env, napi_adjust_external_memory(env, 1, &adjustedValue));
+  NAPI_CALL(env, napi_create_double(env, adjustedValue, &result));
+
+  return result;
+}
+
 void Init(napi_env env, napi_value exports, napi_value module, void* priv) {
   napi_property_descriptor descriptors[] = {
     DECLARE_NAPI_PROPERTY("testStrictEquals", testStrictEquals),
@@ -222,6 +232,7 @@ void Init(napi_env env, napi_value exports, napi_value module, void* priv) {
     DECLARE_NAPI_PROPERTY("testFinalizeWrap", test_finalize_wrap),
     DECLARE_NAPI_PROPERTY("finalizeWasCalled", finalize_was_called),
     DECLARE_NAPI_PROPERTY("derefItemWasCalled", deref_item_was_called),
+    DECLARE_NAPI_PROPERTY("testAdjustExternalMemory", testAdjustExternalMemory)
   };
 
   NAPI_CALL_RETURN_VOID(env, napi_define_properties(