v8: add setHeapSnapshotNearHeapLimit

PR-URL: #44420
Refs: #33010
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

Author: theanarkh

doc/api/v8.md

@@ -343,6 +343,20 @@ if (isMainThread) {
 }
 ```
 
+## `v8.setHeapSnapshotNearHeapLimit(limit)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `limit` {integer}
+
+The API is a no-op if `--heapsnapshot-near-heap-limit` is already set from the
+command line or the API is called more than once. `limit` must be a positive
+integer. See [`--heapsnapshot-near-heap-limit`][] for more information.
+
 ## Serialization API
 
 The serialization API provides means of serializing JavaScript values in a way
@@ -987,6 +1001,7 @@ Returns true if the Node.js instance is run to build a snapshot.
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 [Hook Callbacks]: #hook-callbacks
 [V8]: https://developers.google.com/v8/
+[`--heapsnapshot-near-heap-limit`]: cli.md#--heapsnapshot-near-heap-limitmax_count
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md
 [`DefaultDeserializer`]: #class-v8defaultdeserializer

lib/v8.js

@@ -33,7 +33,7 @@ const {
 } = primordials;
 
 const { Buffer } = require('buffer');
-const { validateString } = require('internal/validators');
+const { validateString, validateUint32 } = require('internal/validators');
 const {
   Serializer,
   Deserializer
@@ -59,6 +59,7 @@ const {
 } = internalBinding('heap_utils');
 const { HeapSnapshotStream } = require('internal/heap_utils');
 const promiseHooks = require('internal/promise_hooks');
+const { getOptionValue } = require('internal/options');
 
 /**
  * Generates a snapshot of the current V8 heap
@@ -95,6 +96,7 @@ const {
   updateHeapStatisticsBuffer,
   updateHeapSpaceStatisticsBuffer,
   updateHeapCodeStatisticsBuffer,
+  setHeapSnapshotNearHeapLimit: _setHeapSnapshotNearHeapLimit,
 
   // Properties for heap statistics buffer extraction.
   kTotalHeapSizeIndex,
@@ -223,6 +225,18 @@ function getHeapCodeStatistics() {
   };
 }
 
+let heapSnapshotNearHeapLimitCallbackAdded = false;
+function setHeapSnapshotNearHeapLimit(limit) {
+  validateUint32(limit, 'limit', 1);
+  if (heapSnapshotNearHeapLimitCallbackAdded ||
+      getOptionValue('--heapsnapshot-near-heap-limit') > 0
+  ) {
+    return;
+  }
+  heapSnapshotNearHeapLimitCallbackAdded = true;
+  _setHeapSnapshotNearHeapLimit(limit);
+}
+
 /* V8 serialization API */
 
 /* JS methods for the base objects */
@@ -384,5 +398,6 @@ module.exports = {
   serialize,
   writeHeapSnapshot,
   promiseHooks,
-  startupSnapshot
+  startupSnapshot,
+  setHeapSnapshotNearHeapLimit,
 };

src/env-inl.h

@@ -896,6 +896,24 @@ v8::Local<v8::Context> Environment::context() const {
   return PersistentToLocal::Strong(context_);
 }
 
+inline void Environment::set_heap_snapshot_near_heap_limit(uint32_t limit) {
+  heap_snapshot_near_heap_limit_ = limit;
+}
+
+inline void Environment::AddHeapSnapshotNearHeapLimitCallback() {
+  DCHECK(!heapsnapshot_near_heap_limit_callback_added_);
+  heapsnapshot_near_heap_limit_callback_added_ = true;
+  isolate_->AddNearHeapLimitCallback(Environment::NearHeapLimitCallback, this);
+}
+
+inline void Environment::RemoveHeapSnapshotNearHeapLimitCallback(
+    size_t heap_limit) {
+  DCHECK(heapsnapshot_near_heap_limit_callback_added_);
+  heapsnapshot_near_heap_limit_callback_added_ = false;
+  isolate_->RemoveNearHeapLimitCallback(Environment::NearHeapLimitCallback,
+                                        heap_limit);
+}
+
 }  // namespace node
 
 // These two files depend on each other. Including base_object-inl.h after this

src/env.cc

@@ -770,6 +770,9 @@ Environment::Environment(IsolateData* isolate_data,
   inspector_host_port_ = std::make_shared<ExclusiveAccess<HostPort>>(
       options_->debug_options().host_port);
 
+  heap_snapshot_near_heap_limit_ =
+      static_cast<uint32_t>(options_->heap_snapshot_near_heap_limit);
+
   if (!(flags_ & EnvironmentFlags::kOwnsProcessState)) {
     set_abort_on_uncaught_exception(false);
   }
@@ -884,9 +887,8 @@ Environment::~Environment() {
   // FreeEnvironment() should have set this.
   CHECK(is_stopping());
 
-  if (options_->heap_snapshot_near_heap_limit > heap_limit_snapshot_taken_) {
-    isolate_->RemoveNearHeapLimitCallback(Environment::NearHeapLimitCallback,
-                                          0);
+  if (heapsnapshot_near_heap_limit_callback_added_) {
+    RemoveHeapSnapshotNearHeapLimitCallback(0);
   }
 
   isolate()->GetHeapProfiler()->RemoveBuildEmbedderGraphCallback(
@@ -2029,8 +2031,7 @@ size_t Environment::NearHeapLimitCallback(void* data,
     Debug(env,
           DebugCategory::DIAGNOSTICS,
           "Not generating snapshots because it's too risky.\n");
-    env->isolate()->RemoveNearHeapLimitCallback(NearHeapLimitCallback,
-                                                initial_heap_limit);
+    env->RemoveHeapSnapshotNearHeapLimitCallback(initial_heap_limit);
     // The new limit must be higher than current_heap_limit or V8 might
     // crash.
     return current_heap_limit + 1;
@@ -2050,17 +2051,15 @@ size_t Environment::NearHeapLimitCallback(void* data,
 
   // Remove the callback first in case it's triggered when generating
   // the snapshot.
-  env->isolate()->RemoveNearHeapLimitCallback(NearHeapLimitCallback,
-                                              initial_heap_limit);
+  env->RemoveHeapSnapshotNearHeapLimitCallback(initial_heap_limit);
 
   heap::WriteSnapshot(env->isolate(), filename.c_str());
   env->heap_limit_snapshot_taken_ += 1;
 
   // Don't take more snapshots than the number specified by
   // --heapsnapshot-near-heap-limit.
-  if (env->heap_limit_snapshot_taken_ <
-      env->options_->heap_snapshot_near_heap_limit) {
-    env->isolate()->AddNearHeapLimitCallback(NearHeapLimitCallback, env);
+  if (env->heap_limit_snapshot_taken_ < env->heap_snapshot_near_heap_limit_) {
+    env->AddHeapSnapshotNearHeapLimitCallback();
   }
 
   FPrintF(stderr, "Wrote snapshot to %s\n", filename.c_str());

src/env.h

@@ -1459,6 +1459,12 @@ class Environment : public MemoryRetainer {
   template <typename T>
   void ForEachBindingData(T&& iterator);
 
+  inline void set_heap_snapshot_near_heap_limit(uint32_t limit);
+
+  inline void AddHeapSnapshotNearHeapLimitCallback();
+
+  inline void RemoveHeapSnapshotNearHeapLimitCallback(size_t heap_limit);
+
  private:
   inline void ThrowError(v8::Local<v8::Value> (*fun)(v8::Local<v8::String>),
                          const char* errmsg);
@@ -1516,7 +1522,9 @@ class Environment : public MemoryRetainer {
   std::string exec_path_;
 
   bool is_processing_heap_limit_callback_ = false;
-  int64_t heap_limit_snapshot_taken_ = 0;
+  uint32_t heap_limit_snapshot_taken_ = 0;
+  uint32_t heap_snapshot_near_heap_limit_ = 0;
+  bool heapsnapshot_near_heap_limit_callback_added_ = false;
 
   uint32_t module_id_counter_ = 0;
   uint32_t script_id_counter_ = 0;

src/node.cc

@@ -282,9 +282,8 @@ static void AtomicsWaitCallback(Isolate::AtomicsWaitEvent event,
 void Environment::InitializeDiagnostics() {
   isolate_->GetHeapProfiler()->AddBuildEmbedderGraphCallback(
       Environment::BuildEmbedderGraph, this);
-  if (options_->heap_snapshot_near_heap_limit > 0) {
-    isolate_->AddNearHeapLimitCallback(Environment::NearHeapLimitCallback,
-                                       this);
+  if (heap_snapshot_near_heap_limit_ > 0) {
+    AddHeapSnapshotNearHeapLimitCallback();
   }
   if (options_->trace_uncaught)
     isolate_->SetCaptureStackTraceForUncaughtExceptions(true);

src/node_v8.cc

@@ -155,6 +155,15 @@ void CachedDataVersionTag(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(result);
 }
 
+void SetHeapSnapshotNearHeapLimit(const FunctionCallbackInfo<Value>& args) {
+  CHECK(args[0]->IsUint32());
+  Environment* env = Environment::GetCurrent(args);
+  uint32_t limit = args[0].As<v8::Uint32>()->Value();
+  CHECK_GT(limit, 0);
+  env->AddHeapSnapshotNearHeapLimitCallback();
+  env->set_heap_snapshot_near_heap_limit(limit);
+}
+
 void UpdateHeapStatisticsBuffer(const FunctionCallbackInfo<Value>& args) {
   BindingData* data = Environment::GetBindingData<BindingData>(args);
   HeapStatistics s;
@@ -212,6 +221,8 @@ void Initialize(Local<Object> target,
                              CachedDataVersionTag);
   env->SetMethod(
       target, "updateHeapStatisticsBuffer", UpdateHeapStatisticsBuffer);
+  env->SetMethodNoSideEffect(target, "setHeapSnapshotNearHeapLimit",
+                             SetHeapSnapshotNearHeapLimit);
 
   env->SetMethod(
       target, "updateHeapCodeStatisticsBuffer", UpdateHeapCodeStatisticsBuffer);
@@ -259,6 +270,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(UpdateHeapCodeStatisticsBuffer);
   registry->Register(UpdateHeapSpaceStatisticsBuffer);
   registry->Register(SetFlagsFromString);
+  registry->Register(SetHeapSnapshotNearHeapLimit);
 }
 
 }  // namespace v8_utils

test/fixtures/workload/grow-and-set-near-heap-limit.js

@@ -0,0 +1,9 @@
+'use strict';
+const path = require('path');
+const v8 = require('v8');
+
+v8.setHeapSnapshotNearHeapLimit(+process.env.limit);
+if (process.env.limit2) {
+  v8.setHeapSnapshotNearHeapLimit(+process.env.limit2);
+}
+require(path.resolve(__dirname, 'grow.js'));

test/fixtures/workload/grow-worker-and-set-near-heap-limit.js

@@ -0,0 +1,15 @@
+'use strict';
+const path = require('path');
+const { Worker } = require('worker_threads');
+const max_snapshots = parseInt(process.env.TEST_SNAPSHOTS) || 1;
+new Worker(path.join(__dirname, 'grow-and-set-near-heap-limit.js'), {
+  env: {
+    ...process.env,
+    limit: max_snapshots,
+  },
+  resourceLimits: {
+    maxOldGenerationSizeMb:
+      parseInt(process.env.TEST_OLD_SPACE_SIZE) || 20
+  }
+});
+

test/parallel/test-heapsnapshot-near-heap-limit-by-api-in-worker.js

@@ -0,0 +1,41 @@
+// Copy from test-heapsnapshot-near-heap-limit-worker.js
+'use strict';
+
+require('../common');
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const fixtures = require('../common/fixtures');
+const fs = require('fs');
+
+const env = {
+  ...process.env,
+  NODE_DEBUG_NATIVE: 'diagnostics'
+};
+
+{
+  tmpdir.refresh();
+  const child = spawnSync(process.execPath, [
+    fixtures.path('workload', 'grow-worker-and-set-near-heap-limit.js'),
+  ], {
+    cwd: tmpdir.path,
+    env: {
+      TEST_SNAPSHOTS: 1,
+      TEST_OLD_SPACE_SIZE: 50,
+      ...env
+    }
+  });
+  console.log(child.stdout.toString());
+  const stderr = child.stderr.toString();
+  console.log(stderr);
+  const risky = /Not generating snapshots because it's too risky/.test(stderr);
+  if (!risky) {
+    // There should be one snapshot taken and then after the
+    // snapshot heap limit callback is popped, the OOM callback
+    // becomes effective.
+    assert(stderr.includes('ERR_WORKER_OUT_OF_MEMORY'));
+    const list = fs.readdirSync(tmpdir.path)
+      .filter((file) => file.endsWith('.heapsnapshot'));
+    assert.strictEqual(list.length, 1);
+  }
+}