Commit 428dd864890 for nodejs

commit 428dd8648909a321fa2c558bf01abebb17a74647
Author: James M Snell <jasnell@gmail.com>
Date:   Mon Nov 16 07:54:47 2026 -0800

    src: warn when heap would exceed pointer compression limit

    In builds without pointer compression, emit a process warning with
    the code HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT when the heap that
    survives a full garbage collection suggests that it would not fit in
    the 4 GiB cage that limits the heap of each isolate when pointer
    compression is enabled.

    Pointer compression shrinks a heap by at most half, and by about 40%
    in practice, so the warning says the heap is likely to exceed the
    limit from 6.5 GiB, and that it will exceed the limit from 8 GiB.

    The check runs in a GC epilogue callback for mark-compact GCs only,
    is done at most once per Environment, and unregisters itself after
    the warning has been scheduled. The warning can be silenced with
    --disable-warning=HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT.

    Assisted-by: Claude
    Signed-off-by: James M Snell <jasnell@gmail.com>
    PR-URL: https://github.com/nodejs/node/pull/67468
    Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
    Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
    Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>

diff --git a/doc/api/process.md b/doc/api/process.md
index d47983a97b4..2bcac659766 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -598,6 +598,32 @@ A few of the warning types that are most common include:
   that will be ignored rather than treated as an error. One example is use of
   the HTTP response status message when using the HTTP/2 compatibility API.

+#### Heap size and pointer compression
+
+<!-- YAML
+added: REPLACEME
+-->
+
+When Node.js is built with V8 pointer compression enabled, the V8 heap of each
+thread (the main thread and every [`Worker`][]) is limited to 4 GiB, regardless
+of `--max-old-space-size`. Pointer compression reduces heap usage, typically by
+about 40% and never by more than half, so a heap that is larger than 4 GiB
+without pointer compression may or may not fit under that limit.
+
+In builds without pointer compression, Node.js emits a warning with the code
+`'HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT'` when the heap of a thread that
+survives a full garbage collection reaches:
+
+* 6.5 GiB: the heap is likely to exceed the limit with pointer compression.
+* 8 GiB: the heap will exceed the limit with pointer compression.
+
+The warning is emitted at most once per thread, with the wording that matches
+the heap size at the time. Memory outside the V8 heap, such as the contents of
+{ArrayBuffer}s and {Buffer}s, does not count toward the limit.
+
+The warning can be silenced with
+`--disable-warning=HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT`.
+
 ### Event: `'worker'`

 <!-- YAML
diff --git a/src/env-inl.h b/src/env-inl.h
index c2abf1c29a8..dec640a3de0 100644
--- a/src/env-inl.h
+++ b/src/env-inl.h
@@ -1021,6 +1021,12 @@ inline void Environment::RemoveHeapProfileNearHeapLimitCallback(
   }
 }

+inline void Environment::set_pointer_compression_heap_warning_thresholds(
+    uint64_t likely_bytes, uint64_t certain_bytes) {
+  pointer_compression_heap_likely_threshold_ = likely_bytes;
+  pointer_compression_heap_certain_threshold_ = certain_bytes;
+}
+
 }  // namespace node

 // These two files depend on each other. Including base_object-inl.h after this
diff --git a/src/env.cc b/src/env.cc
index 5f8e22073fa..d9096bf089c 100644
--- a/src/env.cc
+++ b/src/env.cc
@@ -1268,6 +1268,7 @@ Environment::~Environment() {
   if (heap_profile_near_heap_limit_callback_added_) {
     RemoveHeapProfileNearHeapLimitCallback(0);
   }
+  RemovePointerCompressionHeapWarningCallback();

   isolate()->GetHeapProfiler()->RemoveBuildEmbedderGraphCallback(
       BuildEmbedderGraph, this);
@@ -2343,6 +2344,84 @@ void Environment::TracePromises(PromiseHookType type,
   PrintCurrentStackTrace(isolate);
 }

+bool Environment::ShouldWarnAboutPointerCompressionHeap() const {
+#if defined(V8_COMPRESS_POINTERS)
+  // The cage already enforces the limit, so there is nothing to warn about.
+  return false;
+#else
+  // 32-bit address spaces cannot hold a 4 GiB heap in the first place.
+  // --no-warnings and --disable-warning are not checked here: like every
+  // other process warning, they only suppress the default stderr output, and
+  // 'warning' listeners still receive the event.
+  return sizeof(void*) == 8;
+#endif
+}
+
+void Environment::AddPointerCompressionHeapWarningCallback() {
+  if (pointer_compression_heap_warning_callback_added_) return;
+  pointer_compression_heap_warning_callback_added_ = true;
+  // Only full GCs: the heap that survives a mark-compact is the closest
+  // approximation of the live heap, and young-generation GCs are frequent.
+  isolate_->AddGCEpilogueCallback(
+      PointerCompressionHeapWarningCallback, this, v8::kGCTypeMarkSweepCompact);
+}
+
+void Environment::RemovePointerCompressionHeapWarningCallback() {
+  if (!pointer_compression_heap_warning_callback_added_) return;
+  pointer_compression_heap_warning_callback_added_ = false;
+  isolate_->RemoveGCEpilogueCallback(PointerCompressionHeapWarningCallback,
+                                     this);
+}
+
+void Environment::PointerCompressionHeapWarningCallback(
+    Isolate* isolate, v8::GCType type, v8::GCCallbackFlags flags, void* data) {
+  Environment* env = static_cast<Environment*>(data);
+  if (env->pointer_compression_heap_warning_scheduled_) return;
+
+  v8::HeapStatistics stats;
+  isolate->GetHeapStatistics(&stats);
+  const uint64_t used = stats.used_heap_size();
+  if (used < env->pointer_compression_heap_likely_threshold_ &&
+      used < env->pointer_compression_heap_certain_threshold_) {
+    return;
+  }
+  // The wording is decided once, when the warning is first triggered.
+  const bool certain = used >= env->pointer_compression_heap_certain_threshold_;
+
+  // JavaScript cannot run inside a GC callback, and V8 does not allow
+  // removing a GC callback while it is iterating over them, so do both from
+  // an immediate instead.
+  env->pointer_compression_heap_warning_scheduled_ = true;
+  env->SetImmediate(
+      [used, certain](Environment* env) {
+        env->RemovePointerCompressionHeapWarningCallback();
+        constexpr uint64_t kMiB = 1024 * 1024;
+        std::string thread =
+            env->is_main_thread()
+                ? std::string("the main thread")
+                : SPrintF("worker thread %d", env->thread_id());
+        std::string outcome =
+            certain ? "Pointer compression reduces heap usage by at most "
+                      "half, so this heap will exceed that limit, and the "
+                      "application will run out of memory"
+                    : "Pointer compression typically reduces heap usage by "
+                      "about 40%, so this heap is likely to exceed that "
+                      "limit, and the application may run out of memory";
+        std::string message = SPrintF(
+            "The V8 heap of %s is using %d MiB after garbage collection. "
+            "When pointer compression is enabled, the heap of each thread is "
+            "limited to %d MiB. %s in Node.js builds that enable pointer "
+            "compression.",
+            thread,
+            used / kMiB,
+            kPointerCompressionCageSize / kMiB,
+            outcome);
+        USE(ProcessEmitWarningGeneric(
+            env, message, "Warning", kPointerCompressionHeapWarningCode));
+      },
+      CallbackFlags::kUnrefed);
+}
+
 // V8 only invokes the most recently registered near-heap-limit callback.
 // To allow the snapshot and profile handlers to coexist on the same
 // isolate, both register through this single V8-facing entry point. It fans
diff --git a/src/env.h b/src/env.h
index f47fd051bb6..b8c48352e91 100644
--- a/src/env.h
+++ b/src/env.h
@@ -1118,6 +1118,10 @@ class Environment final : public MemoryRetainer {
   static void BuildEmbedderGraph(v8::Isolate* isolate,
                                  v8::EmbedderGraph* graph,
                                  void* data);
+  static void PointerCompressionHeapWarningCallback(v8::Isolate* isolate,
+                                                    v8::GCType type,
+                                                    v8::GCCallbackFlags flags,
+                                                    void* data);

   inline std::shared_ptr<EnvironmentOptions> options();
   inline std::shared_ptr<ExclusiveAccess<HostPort>> inspector_host_port();
@@ -1209,6 +1213,28 @@ class Environment final : public MemoryRetainer {
   inline void AddHeapProfileNearHeapLimitCallback();
   inline void RemoveHeapProfileNearHeapLimitCallback(size_t heap_limit);

+  // The heap of a single isolate cannot grow beyond the 4 GiB pointer
+  // compression cage in builds that enable pointer compression. In builds
+  // that do not, warn once per Environment when the heap that survives a full
+  // garbage collection suggests that it would not fit:
+  // - Pointer compression shrinks a heap by at most half (only tagged slots
+  //   shrink), so a heap of twice the cage size or more will not fit.
+  // - V8 reports typical savings of about 40%, so a heap of about 6.5 GiB or
+  //   more (4 GiB / 0.6) is likely not to fit.
+  static constexpr uint64_t kPointerCompressionCageSize = uint64_t{1} << 32;
+  static constexpr uint64_t kPointerCompressionHeapLikelyThreshold =
+      uint64_t{13} << 29;  // 6.5 GiB
+  static constexpr uint64_t kPointerCompressionHeapCertainThreshold =
+      2 * kPointerCompressionCageSize;  // 8 GiB
+  static constexpr const char* kPointerCompressionHeapWarningCode =
+      "HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT";
+  bool ShouldWarnAboutPointerCompressionHeap() const;
+  void AddPointerCompressionHeapWarningCallback();
+  void RemovePointerCompressionHeapWarningCallback();
+  // Used by tests to trigger the warning without allocating a large heap.
+  inline void set_pointer_compression_heap_warning_thresholds(
+      uint64_t likely_bytes, uint64_t certain_bytes);
+
   v8::CpuProfilingResult StartCpuProfile(const CpuProfileOptions& options);
   v8::CpuProfile* StopCpuProfile(v8::ProfilerId profile_id);

@@ -1315,6 +1341,15 @@ class Environment final : public MemoryRetainer {
   uint32_t heap_profile_near_heap_limit_ = 0;
   bool heap_profile_near_heap_limit_callback_added_ = false;

+  bool pointer_compression_heap_warning_callback_added_ = false;
+  // Set once the warning has been scheduled, so that later GCs that run
+  // before the callback is removed do not schedule it again.
+  bool pointer_compression_heap_warning_scheduled_ = false;
+  uint64_t pointer_compression_heap_likely_threshold_ =
+      kPointerCompressionHeapLikelyThreshold;
+  uint64_t pointer_compression_heap_certain_threshold_ =
+      kPointerCompressionHeapCertainThreshold;
+
   uint32_t module_id_counter_ = 0;
   uint32_t script_id_counter_ = 0;
   uint32_t function_id_counter_ = 0;
diff --git a/src/node.cc b/src/node.cc
index 8b21ee34c77..6c9b51bfb5e 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -242,6 +242,9 @@ void Environment::InitializeDiagnostics() {
   if (heap_snapshot_near_heap_limit_ > 0) {
     AddHeapSnapshotNearHeapLimitCallback();
   }
+  if (ShouldWarnAboutPointerCompressionHeap()) {
+    AddPointerCompressionHeapWarningCallback();
+  }
   if (options_->trace_uncaught)
     isolate_->SetCaptureStackTraceForUncaughtExceptions(true);
   if (options_->trace_promises) {
diff --git a/src/node_v8.cc b/src/node_v8.cc
index 14b74f4b6d4..40845e1d79d 100644
--- a/src/node_v8.cc
+++ b/src/node_v8.cc
@@ -230,6 +230,22 @@ void SetHeapProfileNearHeapLimit(const FunctionCallbackInfo<Value>& args) {
   env->set_heap_profile_near_heap_limit(limit);
 }

+// Only used by tests, so that the pointer compression heap warning can be
+// exercised without allocating a large heap. Takes the "likely" and the
+// "certain" thresholds in bytes.
+void SetPointerCompressionHeapWarningThresholds(
+    const FunctionCallbackInfo<Value>& args) {
+  CHECK(args[0]->IsNumber());
+  CHECK(args[1]->IsNumber());
+  Environment* env = Environment::GetCurrent(args);
+  double likely = args[0].As<v8::Number>()->Value();
+  double certain = args[1].As<v8::Number>()->Value();
+  CHECK_GE(likely, 0);
+  CHECK_GE(certain, 0);
+  env->set_pointer_compression_heap_warning_thresholds(
+      static_cast<uint64_t>(likely), static_cast<uint64_t>(certain));
+}
+
 void UpdateHeapStatisticsBuffer(const FunctionCallbackInfo<Value>& args) {
   BindingData* data = Realm::GetBindingData<BindingData>(args);
   HeapStatistics s;
@@ -750,6 +766,10 @@ void Initialize(Local<Object> target,
             target,
             "setHeapProfileNearHeapLimit",
             SetHeapProfileNearHeapLimit);
+  SetMethod(context,
+            target,
+            "setPointerCompressionHeapWarningThresholds",
+            SetPointerCompressionHeapWarningThresholds);
   SetMethod(context,
             target,
             "updateHeapStatisticsBuffer",
@@ -862,6 +882,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(GetHashSeed);
   registry->Register(SetHeapSnapshotNearHeapLimit);
   registry->Register(SetHeapProfileNearHeapLimit);
+  registry->Register(SetPointerCompressionHeapWarningThresholds);
   registry->Register(GCProfiler::New);
   registry->Register(GCProfiler::Start);
   registry->Register(GCProfiler::Stop);
diff --git a/test/parallel/test-heap-pointer-compression-warning.js b/test/parallel/test-heap-pointer-compression-warning.js
new file mode 100644
index 00000000000..6b899d2650b
--- /dev/null
+++ b/test/parallel/test-heap-pointer-compression-warning.js
@@ -0,0 +1,134 @@
+// Flags: --no-warnings --expose-internals --expose-gc
+'use strict';
+
+// Tests the HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT warning, which is emitted
+// once per thread when the heap that survives a full GC would not fit in the
+// 4 GiB pointer compression cage. It says the heap "is likely to exceed" the
+// limit from 6.5 GiB and "will exceed" it from 8 GiB. The thresholds are
+// lowered through an internal binding so the test does not need to allocate a
+// large heap.
+
+const common = require('../common');
+
+common.skipIf32Bits();
+if (process.config.variables.v8_enable_pointer_compression) {
+  common.skip('the warning is only emitted without pointer compression');
+}
+
+const assert = require('assert');
+const { internalBinding } = require('internal/test/binding');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { Worker, isMainThread, threadId } = require('worker_threads');
+
+const kCode = 'HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT';
+const kLikely = /is likely to exceed that limit, and the application may run out of memory/;
+const kCertain = /will exceed that limit, and the application will run out of memory/;
+const childFlags = ['--expose-internals', '--expose-gc'];
+
+// Larger than any heap this test can have.
+const kNever = Number.MAX_SAFE_INTEGER;
+
+function triggerWarning(tier) {
+  const { setPointerCompressionHeapWarningThresholds } = internalBinding('v8');
+  if (tier === 'likely') {
+    setPointerCompressionHeapWarningThresholds(1, kNever);
+  } else {
+    setPointerCompressionHeapWarningThresholds(1, 1);
+  }
+  globalThis.gc();
+  // The warning is emitted from an unref'ed immediate, so keep the event loop
+  // alive for one more iteration.
+  setImmediate(() => {});
+}
+
+switch (process.argv[2]) {
+  case 'child':
+    triggerWarning(process.argv[3]);
+    return;
+  case 'worker': {
+    const { parentPort } = require('worker_threads');
+    process.on('warning', (warning) => {
+      if (warning.code !== kCode) return;
+      parentPort.postMessage({ name: warning.name, message: warning.message });
+    });
+    triggerWarning('certain');
+    return;
+  }
+}
+
+// Collect only this warning; requiring internal/test/binding emits its own.
+const warnings = [];
+process.on('warning', (warning) => {
+  if (warning.code === kCode) warnings.push(warning);
+});
+
+// With the default thresholds, an ordinary heap does not trigger the warning.
+globalThis.gc();
+setImmediate(common.mustCall(() => {
+  assert.strictEqual(warnings.length, 0);
+
+  // A heap between the two thresholds gets the "likely" wording.
+  triggerWarning('likely');
+
+  setImmediate(common.mustCall(() => {
+    // The warning is emitted only once per thread, and its wording is decided
+    // when it is first triggered: a heap that later passes the "certain"
+    // threshold does not emit a second warning.
+    internalBinding('v8').setPointerCompressionHeapWarningThresholds(1, 1);
+    globalThis.gc();
+    setImmediate(() => {});
+  }));
+}));
+
+process.on('exit', () => {
+  assert.strictEqual(warnings.length, 1);
+  const [warning] = warnings;
+  assert.strictEqual(warning.name, 'Warning');
+  // The test-worker suite runs this file inside a worker thread.
+  const thread = isMainThread ? 'the main thread' : `worker thread ${threadId}`;
+  assert.match(warning.message,
+               new RegExp(`The V8 heap of ${thread} is using \\d+ MiB`));
+  assert.match(warning.message, /limited to 4096 MiB/);
+  assert.match(warning.message, kLikely);
+  assert.doesNotMatch(warning.message, kCertain);
+});
+
+// A heap at or above the "certain" threshold gets the "will exceed" wording,
+// and the default stderr output includes the code.
+spawnSyncAndAssert(process.execPath, [
+  ...childFlags,
+  __filename,
+  'child',
+  'certain',
+], {
+  stderr(output) {
+    assert.match(
+      output,
+      new RegExp(`\\[${kCode}\\] Warning: The V8 heap of the main thread`));
+    assert.match(output, kCertain);
+    assert.doesNotMatch(output, kLikely);
+  },
+});
+
+// The code can be used to disable the warning.
+spawnSyncAndAssert(process.execPath, [
+  ...childFlags,
+  `--disable-warning=${kCode}`,
+  __filename,
+  'child',
+  'certain',
+], {
+  stderr(output) {
+    assert.doesNotMatch(output, new RegExp(kCode));
+  },
+});
+
+// Each worker thread has its own heap and its own warning.
+const worker = new Worker(__filename, { argv: ['worker'] });
+worker.on('message', common.mustCall((warning) => {
+  assert.strictEqual(warning.name, 'Warning');
+  assert.match(
+    warning.message,
+    new RegExp(`The V8 heap of worker thread ${worker.threadId} is using`));
+  assert.match(warning.message, kCertain);
+}));