Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions src/env-inl.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
79 changes: 79 additions & 0 deletions src/env.cc
Original file line number Diff line number Diff line change
Expand Up @@ -1268,6 +1268,7 @@ Environment::~Environment() {
if (heap_profile_near_heap_limit_callback_added_) {
RemoveHeapProfileNearHeapLimitCallback(0);
}
RemovePointerCompressionHeapWarningCallback();

isolate()->GetHeapProfiler()->RemoveBuildEmbedderGraphCallback(
BuildEmbedderGraph, this);
Expand Down Expand Up @@ -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
Expand Down
35 changes: 35 additions & 0 deletions src/env.h
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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;
Expand Down
3 changes: 3 additions & 0 deletions src/node.cc
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
21 changes: 21 additions & 0 deletions src/node_v8.cc
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -750,6 +766,10 @@ void Initialize(Local<Object> target,
target,
"setHeapProfileNearHeapLimit",
SetHeapProfileNearHeapLimit);
SetMethod(context,
target,
"setPointerCompressionHeapWarningThresholds",
SetPointerCompressionHeapWarningThresholds);
SetMethod(context,
target,
"updateHeapStatisticsBuffer",
Expand Down Expand Up @@ -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);
Expand Down
134 changes: 134 additions & 0 deletions test/parallel/test-heap-pointer-compression-warning.js
Original file line number Diff line number Diff line change
@@ -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);
}));
Loading