src: add heap profile labels and ProfilingArrayBufferAllocator

C++ bindings for the V8 heap profile labels callback:
- RegisterHeapProfileLabels/UnregisterHeapProfileLabels via CPED lookup
- HeapProfileLabelsCallback with O(1) address map + GC-move slow path
- ProfilingArrayBufferAllocator for per-label Buffer/ArrayBuffer tracking
- GetAllocationProfile with labels and externalBytes
- Cleanup hooks for environment teardown
- Build flag conditioning on v8_enable_continuation_preserved_embedder_data

Signed-off-by: Rudolf Meijering <skaapgif@gmail.com>

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,7 +15,9 @@
 #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_handle_address.h"
 #include "node_wasm_web_api.h"
 #include "uv.h"
 #ifdef NODE_ENABLE_VTUNE_PROFILING
@@ -191,11 +193,147 @@ 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,
+    std::unordered_map<uintptr_t,
+                       v8_utils::HeapProfileLabelEntry>* label_map) {
+  Mutex::ScopedLock lock(mutex_);
+  isolate_ = isolate;
+  label_map_ = label_map;
+  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;
+  label_map_ = 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 || label_map_ == nullptr) 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->IsUndefined() || cped->IsNull()) return {};
+
+  uintptr_t addr = GetLocalAddress(cped);
+  if (addr == 0) return {};  // Smi::zero() — no ALS context
+
+  // O(1) lookup by tagged object address.
+  auto it = label_map_->find(addr);
+  if (it != label_map_->end() && !it->second.labels.empty()) {
+    return it->second.labels;
+  }
+
+  // Slow path: GC may have moved the object. Scan by identity.
+  for (const auto& [key, entry] : *label_map_) {
+    if (!entry.context_key.IsEmpty() && entry.context_key == cped) {
+      if (!entry.labels.empty()) {
+        // Copy labels before extract invalidates the reference.
+        auto result = entry.labels;
+        // Rehash for future fast-path hits.
+        auto node = label_map_->extract(key);
+        node.key() = addr;
+        label_map_->insert(std::move(node));
+        return result;
+      }
+      break;
+    }
+  }
+
+  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_handle_address.h

@@ -0,0 +1,27 @@
+#ifndef SRC_NODE_HANDLE_ADDRESS_H_
+#define SRC_NODE_HANDLE_ADDRESS_H_
+
+#include "v8-internal.h"
+#include "v8-local-handle.h"
+
+namespace node {
+
+// Extract the tagged V8 object address from a Local handle.
+// Uses V8's ValueHelper which correctly handles both indirect handles
+// (Address* location_) and direct handles (V8_ENABLE_DIRECT_LOCAL).
+//
+// v8::internal::ValueHelper::ValueAsAddress is declared in V8's semi-public
+// header <v8-internal.h>, which is distributed with V8 and intended for
+// embedder use (it backs the V8 API handle machinery). However, internal APIs
+// may change across V8 major versions. This is the recommended approach per
+// the V8 team for extracting tagged addresses from Local handles under both
+// direct and indirect handle modes. If V8 removes or renames ValueHelper in a
+// future update, this callsite will need to be adjusted accordingly.
+inline uintptr_t GetLocalAddress(v8::Local<v8::Value> handle) {
+  return static_cast<uintptr_t>(
+      v8::internal::ValueHelper::ValueAsAddress(*handle));
+}
+
+}  // namespace node
+
+#endif  // SRC_NODE_HANDLE_ADDRESS_H_

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,59 @@ class DebuggingArrayBufferAllocator final : public NodeArrayBufferAllocator {
   std::unordered_map<void*, size_t> allocations_;
 };
 
+// Forward declarations for heap profile label tracking.
+namespace v8_utils {
+struct HeapProfileLabelEntry;
+}
+
+// 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,
+      std::unordered_map<uintptr_t,
+                         v8_utils::HeapProfileLabelEntry>* label_map);
+  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_label_map (not owned).
+  std::unordered_map<uintptr_t,
+                     v8_utils::HeapProfileLabelEntry>* label_map_ = 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);