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);
+}));