worker: add worker.getHeapStatistics()

Adds worker.getHeapStatistics() so that the heap usage of the worker
could be observer from the parent thread.

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

doc/api/worker_threads.md

@@ -1337,6 +1337,31 @@ If the Worker thread is no longer running, which may occur before the
 [`'exit'` event][] is emitted, the returned `Promise` is rejected
 immediately with an [`ERR_WORKER_NOT_RUNNING`][] error.
 
+### `worker.getHeapStatistics()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* returns: {object}
+  * `total_heap_size` {number}
+  * `total_heap_size_executable` {number}
+  * `total_physical_size` {number}
+  * `total_available_size` {number}
+  * `used_heap_size` {number}
+  * `heap_size_limit` {number}
+  * `malloced_memory` {number}
+  * `peak_malloced_memory` {number}
+  * `does_zap_garbage` {number}
+  * `number_of_native_contexts` {number}
+  * `number_of_detached_contexts` {number}
+  * `total_global_handles_size` {number}
+  * `used_global_handles_size` {number}
+  * `external_memory` {number}
+
+This method is identical to [`v8.getHeapStatistics()`][] but it allows the
+statistics to be observed from outside the actual thread.
+
 ### `worker.performance`
 
 <!-- YAML
@@ -1362,7 +1387,7 @@ added:
   `eventLoopUtilization()`.
 * `utilization2` {Object} The result of a previous call to
   `eventLoopUtilization()` prior to `utilization1`.
-* Returns: {Object}
+* returns: {object}
   * `idle` {number}
   * `active` {number}
   * `utilization` {number}
@@ -1631,6 +1656,7 @@ thread spawned will spawn another until the application crashes.
 [`require('node:worker_threads').workerData`]: #workerworkerdata
 [`trace_events`]: tracing.md
 [`v8.getHeapSnapshot()`]: v8.md#v8getheapsnapshotoptions
+[`v8.getHeapStatistics()`]: v8.md#v8getheapstatistics
 [`vm`]: vm.md
 [`worker.SHARE_ENV`]: #workershare_env
 [`worker.on('message')`]: #event-message_1

lib/internal/worker.js

@@ -459,6 +459,12 @@ class Worker extends EventEmitter {
       };
     });
   }
+
+  getHeapStatistics() {
+    if (this[kHandle] === null) return {};
+
+    return this[kHandle].getHeapStatistics();
+  }
 }
 
 /**

src/node_worker.cc

@@ -812,6 +812,68 @@ void Worker::Unref(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+void Worker::GetHeapStatistics(const FunctionCallbackInfo<Value>& args) {
+  Worker* w;
+  ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
+
+  v8::HeapStatistics heap_stats;
+  w->isolate_->GetHeapStatistics(&heap_stats);
+
+  auto* isolate = args.GetIsolate();
+  Local<Context> currentContext = isolate->GetCurrentContext();
+
+  Local<Object> stats = Object::New(isolate);
+
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "total_heap_size").ToLocalChecked(),
+      Number::New(isolate, heap_stats.total_heap_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "total_heap_size_executable")
+        .ToLocalChecked(),
+      Number::New(isolate, heap_stats.total_heap_size_executable()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "total_physical_size").ToLocalChecked(),
+      Number::New(isolate, heap_stats.total_physical_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "total_available_size").ToLocalChecked(),
+      Number::New(isolate, heap_stats.total_available_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "used_heap_size").ToLocalChecked(),
+      Number::New(isolate, heap_stats.used_heap_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "heap_size_limit").ToLocalChecked(),
+      Number::New(isolate, heap_stats.heap_size_limit()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "malloced_memory").ToLocalChecked(),
+      Number::New(isolate, heap_stats.malloced_memory()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "peak_malloced_memory").ToLocalChecked(),
+      Number::New(isolate, heap_stats.peak_malloced_memory()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "does_zap_garbage").ToLocalChecked(),
+      Boolean::New(isolate, heap_stats.does_zap_garbage()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "number_of_native_contexts")
+        .ToLocalChecked(),
+      Number::New(isolate, heap_stats.number_of_native_contexts()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "number_of_detached_contexts")
+        .ToLocalChecked(),
+      Number::New(isolate, heap_stats.number_of_detached_contexts()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "total_global_handles_size")
+        .ToLocalChecked(),
+      Number::New(isolate, heap_stats.total_global_handles_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "used_global_handles_size").ToLocalChecked(),
+      Number::New(isolate, heap_stats.used_global_handles_size()));
+  stats->Set(currentContext,
+      String::NewFromUtf8(isolate, "external_memory").ToLocalChecked(),
+      Number::New(isolate, heap_stats.external_memory()));
+
+  args.GetReturnValue().Set(stats);
+}
+
 void Worker::GetResourceLimits(const FunctionCallbackInfo<Value>& args) {
   Worker* w;
   ASSIGN_OR_RETURN_UNWRAP(&w, args.This());
@@ -992,6 +1054,8 @@ void CreateWorkerPerIsolateProperties(IsolateData* isolate_data,
     SetProtoMethod(isolate, w, "takeHeapSnapshot", Worker::TakeHeapSnapshot);
     SetProtoMethod(isolate, w, "loopIdleTime", Worker::LoopIdleTime);
     SetProtoMethod(isolate, w, "loopStartTime", Worker::LoopStartTime);
+    SetProtoMethod(isolate, w, "getHeapStatistics", Worker::GetHeapStatistics);
+
 
     SetConstructorFunction(isolate, target, "Worker", w);
   }

src/node_worker.h

@@ -78,6 +78,8 @@ class Worker : public AsyncWrap {
   static void TakeHeapSnapshot(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void LoopIdleTime(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void LoopStartTime(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetHeapStatistics(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
 
  private:
   bool CreateEnvMessagePort(Environment* env);

test/parallel/test-worker-heap-statistics.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const common = require('../common');
+const fixtures = require('../common/fixtures');
+
+common.skipIfInspectorDisabled();
+
+const {
+  Worker,
+  isMainThread,
+} = require('worker_threads');
+
+if (!isMainThread) {
+  common.skip('This test only works on a main thread');
+}
+
+// Ensures that worker.getHeapStatistics() returns valid data
+
+const assert = require('assert');
+
+if (isMainThread) {
+  const name = 'Hello Thread';
+  const worker = new Worker(fixtures.path('worker-name.js'), {
+    name,
+  });
+  worker.once('message', common.mustCall((message) => {
+    const stats = worker.getHeapStatistics();
+    const keys = [
+      `total_heap_size`,
+      `total_heap_size_executable`,
+      `total_physical_size`,
+      `total_available_size`,
+      `used_heap_size`,
+      `heap_size_limit`,
+      `malloced_memory`,
+      `peak_malloced_memory`,
+      `does_zap_garbage`,
+      `number_of_native_contexts`,
+      `number_of_detached_contexts`,
+      `total_global_handles_size`,
+      `used_global_handles_size`,
+      `external_memory`,
+    ].sort();
+    assert.deepStrictEqual(keys, Object.keys(stats).sort());
+    for (const key of keys) {
+      if (key === 'does_zap_garbage') {
+        assert.strictEqual(typeof stats[key], 'boolean', `Expected ${key} to be a boolean`);
+        assert.strictEqual(stats[key], false);
+        continue;
+      }
+      assert.strictEqual(typeof stats[key], 'number', `Expected ${key} to be a number`);
+      assert.ok(stats[key] >= 0, `Expected ${key} to be >= 0`);
+    }
+
+    worker.postMessage('done');
+  }));
+}