src: add heap profile labels and ProfilingAllocator

C++ bindings for V8 heap profile labels with ALS store lookup:
- HeapProfileLabelsCallback reads the ALS store directly from the
  captured CPED (AsyncContextFrame Map) at profile-read time
- Uses Map::AsArray() + linear scan for ALS key lookup, safe inside
  DisallowJavascriptExecution (ArrayBuffer allocator context)
- ProfilingArrayBufferAllocator tracks per-label external memory
  (Buffer/ArrayBuffer) using the same CPED-based label resolution
- SetHeapProfileLabelsStore receives the ALS key from JS at init time
- GetAllocationProfile returns samples with labels and externalBytes
- Cleanup hooks for environment teardown
- Node.js cctests for label registration, callback, and cleanup

Signed-off-by: Rudolf Meijering <[email protected]>

Author: rudolf

node.gyp

@@ -4,6 +4,7 @@
     'v8_trace_maps%': 0,
     'v8_enable_pointer_compression%': 0,
     'v8_enable_31bit_smis_on_64bit_arch%': 0,
+    'v8_enable_continuation_preserved_embedder_data%': 1,
     'force_dynamic_crt%': 0,
     'node_builtin_modules_path%': '',
     'node_core_target_name%': 'node',
@@ -937,6 +938,12 @@
       'msvs_disabled_warnings!': [4244],
 
       'conditions': [
+        [ 'v8_enable_continuation_preserved_embedder_data==1', {
+          'defines': [
+            # Enable heap profiler sample labels when CPED is available.
+            'V8_HEAP_PROFILER_SAMPLE_LABELS',
+          ],
+        }],
         [ 'openssl_default_cipher_list!=""', {
           'defines': [
             'NODE_OPENSSL_DEFAULT_CIPHER_LIST="<(openssl_default_cipher_list)"'
@@ -1322,6 +1329,11 @@
       'sources': [ '<@(node_cctest_sources)' ],
 
       'conditions': [
+        [ 'v8_enable_continuation_preserved_embedder_data==1', {
+          'defines': [
+            'V8_HEAP_PROFILER_SAMPLE_LABELS',
+          ],
+        }],
         [ 'node_shared_gtest=="false"', {
           'dependencies': [
             'deps/googletest/googletest.gyp:gtest',

src/api/environment.cc

@@ -15,6 +15,7 @@
 #include "node_realm-inl.h"
 #include "node_shadow_realm.h"
 #include "node_snapshot_builder.h"
+#include "node_v8.h"
 #include "node_v8_platform-inl.h"
 #include "node_wasm_web_api.h"
 #include "uv.h"
@@ -191,11 +192,159 @@ void DebuggingArrayBufferAllocator::RegisterPointerInternal(void* data,
   allocations_[data] = size;
 }
 
+void* ProfilingArrayBufferAllocator::Allocate(size_t size) {
+  void* ret = NodeArrayBufferAllocator::Allocate(size);
+  if (ret != nullptr && enabled_.load(std::memory_order_acquire)) {
+    LabelPairs labels = FindCurrentLabels();
+    if (!labels.empty()) {
+      std::string key = SerializeLabels(labels);
+      Mutex::ScopedLock lock(mutex_);
+      allocations_[ret] = {key, size};
+      auto& entry = per_label_bytes_[key];
+      if (entry.labels.empty()) entry.labels = std::move(labels);
+      entry.bytes += static_cast<int64_t>(size);
+    }
+  }
+  return ret;
+}
+
+void* ProfilingArrayBufferAllocator::AllocateUninitialized(size_t size) {
+  void* ret = NodeArrayBufferAllocator::AllocateUninitialized(size);
+  if (ret != nullptr && enabled_.load(std::memory_order_acquire)) {
+    LabelPairs labels = FindCurrentLabels();
+    if (!labels.empty()) {
+      std::string key = SerializeLabels(labels);
+      Mutex::ScopedLock lock(mutex_);
+      allocations_[ret] = {key, size};
+      auto& entry = per_label_bytes_[key];
+      if (entry.labels.empty()) entry.labels = std::move(labels);
+      entry.bytes += static_cast<int64_t>(size);
+    }
+  }
+  return ret;
+}
+
+void ProfilingArrayBufferAllocator::Free(void* data, size_t size) {
+  if (enabled_.load(std::memory_order_acquire)) {
+    Mutex::ScopedLock lock(mutex_);
+    auto it = allocations_.find(data);
+    if (it != allocations_.end()) {
+      auto label_it = per_label_bytes_.find(it->second.first);
+      if (label_it != per_label_bytes_.end()) {
+        label_it->second.bytes -= static_cast<int64_t>(it->second.second);
+      }
+      allocations_.erase(it);
+    }
+  }
+  NodeArrayBufferAllocator::Free(data, size);
+}
+
+void ProfilingArrayBufferAllocator::Enable(
+    v8::Isolate* isolate, v8::Global<v8::Value>* als_key) {
+  Mutex::ScopedLock lock(mutex_);
+  isolate_ = isolate;
+  als_key_ = als_key;
+  main_thread_id_ = std::this_thread::get_id();
+  enabled_.store(true, std::memory_order_release);
+}
+
+void ProfilingArrayBufferAllocator::Disable() {
+  enabled_.store(false, std::memory_order_release);
+  Mutex::ScopedLock lock(mutex_);
+  allocations_.clear();
+  per_label_bytes_.clear();
+  isolate_ = nullptr;
+  als_key_ = nullptr;
+}
+
+std::vector<ProfilingArrayBufferAllocator::LabeledBytes>
+ProfilingArrayBufferAllocator::GetPerLabelBytes() const {
+  Mutex::ScopedLock lock(mutex_);
+  std::vector<LabeledBytes> result;
+  for (const auto& [key, entry] : per_label_bytes_) {
+    if (entry.bytes > 0) {
+      result.push_back(entry);
+    }
+  }
+  return result;
+}
+
+std::string ProfilingArrayBufferAllocator::SerializeLabels(
+    const LabelPairs& labels) {
+  std::string key;
+  for (const auto& [k, v] : labels) {
+    if (!key.empty()) key += '\0';
+    key += k;
+    key += '\0';
+    key += v;
+  }
+  return key;
+}
+
+ProfilingArrayBufferAllocator::LabelPairs
+ProfilingArrayBufferAllocator::FindCurrentLabels() {
+  // Skip non-main-thread allocations (SharedArrayBuffer from workers).
+  if (std::this_thread::get_id() != main_thread_id_) return {};
+  if (isolate_ == nullptr || als_key_ == nullptr || als_key_->IsEmpty()) {
+    return {};
+  }
+
+  // Read CPED via public V8 API. This is safe because:
+  // 1. ArrayBuffer allocator runs in normal JS context, not during GC
+  // 2. HandleScope is always active during JS execution
+  v8::Local<v8::Value> cped =
+      isolate_->GetContinuationPreservedEmbedderData();
+  if (cped.IsEmpty() || !cped->IsMap()) return {};
+
+  v8::HandleScope handle_scope(isolate_);
+  v8::Local<v8::Context> context = isolate_->GetCurrentContext();
+  v8::Local<v8::Map> frame = cped.As<v8::Map>();
+  v8::Local<v8::Value> als_key = als_key_->Get(isolate_);
+
+  // Cannot use Map::Get() here — it calls a JS builtin which is not safe
+  // in DisallowJavascriptExecution (ArrayBuffer allocator is called from
+  // BackingStore::Allocate inside the ArrayBuffer constructor).
+  // Use AsArray() which reads the internal backing store directly without
+  // calling JS builtins, then iterate entries by identity comparison.
+  v8::Local<v8::Array> entries = frame->AsArray();
+  uint32_t entries_len = entries->Length();
+  for (uint32_t i = 0; i + 1 < entries_len; i += 2) {
+    v8::Local<v8::Value> entry_key;
+    if (!entries->Get(context, i).ToLocal(&entry_key)) continue;
+    if (!entry_key->StrictEquals(als_key)) continue;
+
+    // Found the labels ALS entry — value is the flat array.
+    v8::Local<v8::Value> val;
+    if (!entries->Get(context, i + 1).ToLocal(&val) || !val->IsArray()) {
+      return {};
+    }
+
+    // Convert flat [key1, val1, key2, val2, ...] array to string pairs.
+    v8::Local<v8::Array> flat = val.As<v8::Array>();
+    uint32_t len = flat->Length();
+    LabelPairs result;
+    for (uint32_t j = 0; j + 1 < len; j += 2) {
+      v8::Local<v8::Value> k, v;
+      if (!flat->Get(context, j).ToLocal(&k)) return {};
+      if (!flat->Get(context, j + 1).ToLocal(&v)) return {};
+      v8::String::Utf8Value key_str(isolate_, k);
+      v8::String::Utf8Value val_str(isolate_, v);
+      result.emplace_back(*key_str, *val_str);
+    }
+    return result;
+  }
+  return {};
+}
+
 std::unique_ptr<ArrayBufferAllocator> ArrayBufferAllocator::Create(bool debug) {
   if (debug || per_process::cli_options->debug_arraybuffer_allocations)
     return std::make_unique<DebuggingArrayBufferAllocator>();
-  else
-    return std::make_unique<NodeArrayBufferAllocator>();
+  // Always use ProfilingArrayBufferAllocator so that per-label external memory
+  // tracking is available when the sampling heap profiler is started via
+  // v8.startSamplingHeapProfiler(). When profiling is disabled (the default)
+  // the only overhead is a single atomic load (enabled_.load()) on each
+  // Allocate/Free — no hash-map lookups or CPED reads occur.
+  return std::make_unique<ProfilingArrayBufferAllocator>();
 }
 
 ArrayBufferAllocator* CreateArrayBufferAllocator() {

src/node_internals.h

@@ -123,6 +123,8 @@ v8::Maybe<void> InitializePrimordials(v8::Local<v8::Context> context,
 v8::MaybeLocal<v8::Object> InitializePrivateSymbols(
     v8::Local<v8::Context> context, IsolateData* isolate_data);
 
+class ProfilingArrayBufferAllocator;  // Forward declaration.
+
 class NodeArrayBufferAllocator : public ArrayBufferAllocator {
  public:
   void* Allocate(size_t size) override;  // Defined in src/node.cc
@@ -136,6 +138,9 @@ class NodeArrayBufferAllocator : public ArrayBufferAllocator {
   }
 
   NodeArrayBufferAllocator* GetImpl() final { return this; }
+  virtual ProfilingArrayBufferAllocator* GetProfilingAllocator() {
+    return nullptr;
+  }
   inline uint64_t total_mem_usage() const {
     return total_mem_usage_.load(std::memory_order_relaxed);
   }
@@ -164,6 +169,50 @@ class DebuggingArrayBufferAllocator final : public NodeArrayBufferAllocator {
   std::unordered_map<void*, size_t> allocations_;
 };
 
+// Subclass of NodeArrayBufferAllocator that tracks per-label external memory
+// (Buffer/ArrayBuffer backing stores) when heap profiling with labels is active.
+// When disabled (default), overhead is a single relaxed atomic load per alloc.
+class ProfilingArrayBufferAllocator : public NodeArrayBufferAllocator {
+ public:
+  using LabelPairs = std::vector<std::pair<std::string, std::string>>;
+
+  struct LabeledBytes {
+    LabelPairs labels;
+    int64_t bytes = 0;
+  };
+
+  void* Allocate(size_t size) override;
+  void* AllocateUninitialized(size_t size) override;
+  void Free(void* data, size_t size) override;
+  ProfilingArrayBufferAllocator* GetProfilingAllocator() override {
+    return this;
+  }
+
+  // Called from StartSamplingHeapProfiler/StopSamplingHeapProfiler.
+  void Enable(v8::Isolate* isolate, v8::Global<v8::Value>* als_key);
+  void Disable();
+
+  // Returns per-label live external bytes (for getAllocationProfile).
+  std::vector<LabeledBytes> GetPerLabelBytes() const;
+
+ private:
+  LabelPairs FindCurrentLabels();
+  static std::string SerializeLabels(const LabelPairs& labels);
+
+  std::atomic<bool> enabled_{false};
+  v8::Isolate* isolate_ = nullptr;
+  // Borrowed pointer to BindingData::heap_profile_labels_als_key.
+  v8::Global<v8::Value>* als_key_ = nullptr;
+
+  std::thread::id main_thread_id_ = std::this_thread::get_id();
+
+  mutable Mutex mutex_;
+  // Maps allocation pointer to {serialized_label_key, size}.
+  std::unordered_map<void*, std::pair<std::string, size_t>> allocations_;
+  // Per-serialized-label-key entry with full labels and live bytes.
+  std::unordered_map<std::string, LabeledBytes> per_label_bytes_;
+};
+
 namespace Buffer {
 v8::MaybeLocal<v8::Object> Copy(Environment* env, const char* data, size_t len);
 v8::MaybeLocal<v8::Object> New(Environment* env, size_t size);