Skip to content

Commit 139e03c

Browse files
committed
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>
1 parent 7b4c9e3 commit 139e03c

7 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎doc/api/process.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -598,6 +598,32 @@ A few of the warning types that are most common include:
598598
that will be ignored rather than treated as an error. One example is use of
599599
the HTTP response status message when using the HTTP/2 compatibility API.
600600

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

603629
<!-- YAML

‎src/env-inl.h‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1021,6 +1021,12 @@ inline void Environment::RemoveHeapProfileNearHeapLimitCallback(
10211021
}
10221022
}
10231023

1024+
inline void Environment::set_pointer_compression_heap_warning_thresholds(
1025+
uint64_t likely_bytes, uint64_t certain_bytes) {
1026+
pointer_compression_heap_likely_threshold_ = likely_bytes;
1027+
pointer_compression_heap_certain_threshold_ = certain_bytes;
1028+
}
1029+
10241030
} // namespace node
10251031

10261032
// These two files depend on each other. Including base_object-inl.h after this

‎src/env.cc‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1268,6 +1268,7 @@ Environment::~Environment() {
12681268
if (heap_profile_near_heap_limit_callback_added_) {
12691269
RemoveHeapProfileNearHeapLimitCallback(0);
12701270
}
1271+
RemovePointerCompressionHeapWarningCallback();
12711272

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

2347+
bool Environment::ShouldWarnAboutPointerCompressionHeap() const {
2348+
#if defined(V8_COMPRESS_POINTERS)
2349+
// The cage already enforces the limit, so there is nothing to warn about.
2350+
return false;
2351+
#else
2352+
// 32-bit address spaces cannot hold a 4 GiB heap in the first place.
2353+
// --no-warnings and --disable-warning are not checked here: like every
2354+
// other process warning, they only suppress the default stderr output, and
2355+
// 'warning' listeners still receive the event.
2356+
return sizeof(void*) == 8;
2357+
#endif
2358+
}
2359+
2360+
void Environment::AddPointerCompressionHeapWarningCallback() {
2361+
if (pointer_compression_heap_warning_callback_added_) return;
2362+
pointer_compression_heap_warning_callback_added_ = true;
2363+
// Only full GCs: the heap that survives a mark-compact is the closest
2364+
// approximation of the live heap, and young-generation GCs are frequent.
2365+
isolate_->AddGCEpilogueCallback(
2366+
PointerCompressionHeapWarningCallback, this, v8::kGCTypeMarkSweepCompact);
2367+
}
2368+
2369+
void Environment::RemovePointerCompressionHeapWarningCallback() {
2370+
if (!pointer_compression_heap_warning_callback_added_) return;
2371+
pointer_compression_heap_warning_callback_added_ = false;
2372+
isolate_->RemoveGCEpilogueCallback(PointerCompressionHeapWarningCallback,
2373+
this);
2374+
}
2375+
2376+
void Environment::PointerCompressionHeapWarningCallback(
2377+
Isolate* isolate, v8::GCType type, v8::GCCallbackFlags flags, void* data) {
2378+
Environment* env = static_cast<Environment*>(data);
2379+
if (env->pointer_compression_heap_warning_scheduled_) return;
2380+
2381+
v8::HeapStatistics stats;
2382+
isolate->GetHeapStatistics(&stats);
2383+
const uint64_t used = stats.used_heap_size();
2384+
if (used < env->pointer_compression_heap_likely_threshold_ &&
2385+
used < env->pointer_compression_heap_certain_threshold_) {
2386+
return;
2387+
}
2388+
// The wording is decided once, when the warning is first triggered.
2389+
const bool certain = used >= env->pointer_compression_heap_certain_threshold_;
2390+
2391+
// JavaScript cannot run inside a GC callback, and V8 does not allow
2392+
// removing a GC callback while it is iterating over them, so do both from
2393+
// an immediate instead.
2394+
env->pointer_compression_heap_warning_scheduled_ = true;
2395+
env->SetImmediate(
2396+
[used, certain](Environment* env) {
2397+
env->RemovePointerCompressionHeapWarningCallback();
2398+
constexpr uint64_t kMiB = 1024 * 1024;
2399+
std::string thread =
2400+
env->is_main_thread()
2401+
? std::string("the main thread")
2402+
: SPrintF("worker thread %d", env->thread_id());
2403+
std::string outcome =
2404+
certain ? "Pointer compression reduces heap usage by at most "
2405+
"half, so this heap will exceed that limit, and the "
2406+
"application will run out of memory"
2407+
: "Pointer compression typically reduces heap usage by "
2408+
"about 40%, so this heap is likely to exceed that "
2409+
"limit, and the application may run out of memory";
2410+
std::string message = SPrintF(
2411+
"The V8 heap of %s is using %d MiB after garbage collection. "
2412+
"When pointer compression is enabled, the heap of each thread is "
2413+
"limited to %d MiB. %s in Node.js builds that enable pointer "
2414+
"compression.",
2415+
thread,
2416+
used / kMiB,
2417+
kPointerCompressionCageSize / kMiB,
2418+
outcome);
2419+
USE(ProcessEmitWarningGeneric(
2420+
env, message, "Warning", kPointerCompressionHeapWarningCode));
2421+
},
2422+
CallbackFlags::kUnrefed);
2423+
}
2424+
23462425
// V8 only invokes the most recently registered near-heap-limit callback.
23472426
// To allow the snapshot and profile handlers to coexist on the same
23482427
// isolate, both register through this single V8-facing entry point. It fans

‎src/env.h‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1117,6 +1117,10 @@ class Environment final : public MemoryRetainer {
11171117
static void BuildEmbedderGraph(v8::Isolate* isolate,
11181118
v8::EmbedderGraph* graph,
11191119
void* data);
1120+
static void PointerCompressionHeapWarningCallback(v8::Isolate* isolate,
1121+
v8::GCType type,
1122+
v8::GCCallbackFlags flags,
1123+
void* data);
11201124

11211125
inline std::shared_ptr<EnvironmentOptions> options();
11221126
inline std::shared_ptr<ExclusiveAccess<HostPort>> inspector_host_port();
@@ -1208,6 +1212,28 @@ class Environment final : public MemoryRetainer {
12081212
inline void AddHeapProfileNearHeapLimitCallback();
12091213
inline void RemoveHeapProfileNearHeapLimitCallback(size_t heap_limit);
12101214

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

@@ -1314,6 +1340,15 @@ class Environment final : public MemoryRetainer {
13141340
uint32_t heap_profile_near_heap_limit_ = 0;
13151341
bool heap_profile_near_heap_limit_callback_added_ = false;
13161342

1343+
bool pointer_compression_heap_warning_callback_added_ = false;
1344+
// Set once the warning has been scheduled, so that later GCs that run
1345+
// before the callback is removed do not schedule it again.
1346+
bool pointer_compression_heap_warning_scheduled_ = false;
1347+
uint64_t pointer_compression_heap_likely_threshold_ =
1348+
kPointerCompressionHeapLikelyThreshold;
1349+
uint64_t pointer_compression_heap_certain_threshold_ =
1350+
kPointerCompressionHeapCertainThreshold;
1351+
13171352
uint32_t module_id_counter_ = 0;
13181353
uint32_t script_id_counter_ = 0;
13191354
uint32_t function_id_counter_ = 0;

‎src/node.cc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,9 @@ void Environment::InitializeDiagnostics() {
242242
if (heap_snapshot_near_heap_limit_ > 0) {
243243
AddHeapSnapshotNearHeapLimitCallback();
244244
}
245+
if (ShouldWarnAboutPointerCompressionHeap()) {
246+
AddPointerCompressionHeapWarningCallback();
247+
}
245248
if (options_->trace_uncaught)
246249
isolate_->SetCaptureStackTraceForUncaughtExceptions(true);
247250
if (options_->trace_promises) {

‎src/node_v8.cc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,22 @@ void SetHeapProfileNearHeapLimit(const FunctionCallbackInfo<Value>& args) {
230230
env->set_heap_profile_near_heap_limit(limit);
231231
}
232232

233+
// Only used by tests, so that the pointer compression heap warning can be
234+
// exercised without allocating a large heap. Takes the "likely" and the
235+
// "certain" thresholds in bytes.
236+
void SetPointerCompressionHeapWarningThresholds(
237+
const FunctionCallbackInfo<Value>& args) {
238+
CHECK(args[0]->IsNumber());
239+
CHECK(args[1]->IsNumber());
240+
Environment* env = Environment::GetCurrent(args);
241+
double likely = args[0].As<v8::Number>()->Value();
242+
double certain = args[1].As<v8::Number>()->Value();
243+
CHECK_GE(likely, 0);
244+
CHECK_GE(certain, 0);
245+
env->set_pointer_compression_heap_warning_thresholds(
246+
static_cast<uint64_t>(likely), static_cast<uint64_t>(certain));
247+
}
248+
233249
void UpdateHeapStatisticsBuffer(const FunctionCallbackInfo<Value>& args) {
234250
BindingData* data = Realm::GetBindingData<BindingData>(args);
235251
HeapStatistics s;
@@ -750,6 +766,10 @@ void Initialize(Local<Object> target,
750766
target,
751767
"setHeapProfileNearHeapLimit",
752768
SetHeapProfileNearHeapLimit);
769+
SetMethod(context,
770+
target,
771+
"setPointerCompressionHeapWarningThresholds",
772+
SetPointerCompressionHeapWarningThresholds);
753773
SetMethod(context,
754774
target,
755775
"updateHeapStatisticsBuffer",
@@ -862,6 +882,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
862882
registry->Register(GetHashSeed);
863883
registry->Register(SetHeapSnapshotNearHeapLimit);
864884
registry->Register(SetHeapProfileNearHeapLimit);
885+
registry->Register(SetPointerCompressionHeapWarningThresholds);
865886
registry->Register(GCProfiler::New);
866887
registry->Register(GCProfiler::Start);
867888
registry->Register(GCProfiler::Stop);
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
// Flags: --no-warnings --expose-internals --expose-gc
2+
'use strict';
3+
4+
// Tests the HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT warning, which is emitted
5+
// once per thread when the heap that survives a full GC would not fit in the
6+
// 4 GiB pointer compression cage. It says the heap "is likely to exceed" the
7+
// limit from 6.5 GiB and "will exceed" it from 8 GiB. The thresholds are
8+
// lowered through an internal binding so the test does not need to allocate a
9+
// large heap.
10+
11+
const common = require('../common');
12+
13+
common.skipIf32Bits();
14+
if (process.config.variables.v8_enable_pointer_compression) {
15+
common.skip('the warning is only emitted without pointer compression');
16+
}
17+
18+
const assert = require('assert');
19+
const { internalBinding } = require('internal/test/binding');
20+
const { spawnSyncAndAssert } = require('../common/child_process');
21+
const { Worker } = require('worker_threads');
22+
23+
const kCode = 'HEAP_EXCEEDS_POINTER_COMPRESSION_LIMIT';
24+
const kLikely = /is likely to exceed that limit, and the application may run out of memory/;
25+
const kCertain = /will exceed that limit, and the application will run out of memory/;
26+
const childFlags = ['--expose-internals', '--expose-gc'];
27+
28+
// Larger than any heap this test can have.
29+
const kNever = Number.MAX_SAFE_INTEGER;
30+
31+
function triggerWarning(tier) {
32+
const { setPointerCompressionHeapWarningThresholds } = internalBinding('v8');
33+
if (tier === 'likely') {
34+
setPointerCompressionHeapWarningThresholds(1, kNever);
35+
} else {
36+
setPointerCompressionHeapWarningThresholds(1, 1);
37+
}
38+
globalThis.gc();
39+
// The warning is emitted from an unref'ed immediate, so keep the event loop
40+
// alive for one more iteration.
41+
setImmediate(() => {});
42+
}
43+
44+
switch (process.argv[2]) {
45+
case 'child':
46+
triggerWarning(process.argv[3]);
47+
return;
48+
case 'worker': {
49+
const { parentPort } = require('worker_threads');
50+
process.on('warning', (warning) => {
51+
if (warning.code !== kCode) return;
52+
parentPort.postMessage({ name: warning.name, message: warning.message });
53+
});
54+
triggerWarning('certain');
55+
return;
56+
}
57+
}
58+
59+
// Collect only this warning; requiring internal/test/binding emits its own.
60+
const warnings = [];
61+
process.on('warning', (warning) => {
62+
if (warning.code === kCode) warnings.push(warning);
63+
});
64+
65+
// With the default thresholds, an ordinary heap does not trigger the warning.
66+
globalThis.gc();
67+
setImmediate(common.mustCall(() => {
68+
assert.strictEqual(warnings.length, 0);
69+
70+
// A heap between the two thresholds gets the "likely" wording.
71+
triggerWarning('likely');
72+
73+
setImmediate(common.mustCall(() => {
74+
// The warning is emitted only once per thread, and its wording is decided
75+
// when it is first triggered: a heap that later passes the "certain"
76+
// threshold does not emit a second warning.
77+
internalBinding('v8').setPointerCompressionHeapWarningThresholds(1, 1);
78+
globalThis.gc();
79+
setImmediate(() => {});
80+
}));
81+
}));
82+
83+
process.on('exit', () => {
84+
assert.strictEqual(warnings.length, 1);
85+
const [warning] = warnings;
86+
assert.strictEqual(warning.name, 'Warning');
87+
assert.match(warning.message, /The V8 heap of the main thread is using \d+ MiB/);
88+
assert.match(warning.message, /limited to 4096 MiB/);
89+
assert.match(warning.message, kLikely);
90+
assert.doesNotMatch(warning.message, kCertain);
91+
});
92+
93+
// A heap at or above the "certain" threshold gets the "will exceed" wording,
94+
// and the default stderr output includes the code.
95+
spawnSyncAndAssert(process.execPath, [
96+
...childFlags,
97+
__filename,
98+
'child',
99+
'certain',
100+
], {
101+
stderr(output) {
102+
assert.match(
103+
output,
104+
new RegExp(`\\[${kCode}\\] Warning: The V8 heap of the main thread`));
105+
assert.match(output, kCertain);
106+
assert.doesNotMatch(output, kLikely);
107+
},
108+
});
109+
110+
// The code can be used to disable the warning.
111+
spawnSyncAndAssert(process.execPath, [
112+
...childFlags,
113+
`--disable-warning=${kCode}`,
114+
__filename,
115+
'child',
116+
'certain',
117+
], {
118+
stderr(output) {
119+
assert.doesNotMatch(output, new RegExp(kCode));
120+
},
121+
});
122+
123+
// Each worker thread has its own heap and its own warning.
124+
const worker = new Worker(__filename, { argv: ['worker'] });
125+
worker.on('message', common.mustCall((warning) => {
126+
assert.strictEqual(warning.name, 'Warning');
127+
assert.match(
128+
warning.message,
129+
new RegExp(`The V8 heap of worker thread ${worker.threadId} is using`));
130+
assert.match(warning.message, kCertain);
131+
}));

0 commit comments

Comments
 (0)