From aa6c65620219d2811b1adda4c94842fafd44de27 Mon Sep 17 00:00:00 2001 From: Rudolf Meijering Date: Tue, 17 Nov 2026 15:18:42 +0100 Subject: [PATCH 1/2] worker: respect resourceLimits when --max-old-space-size is set Handle --max-old-space-size in PerIsolateOptions and apply it via v8::ResourceConstraints::set_max_old_generation_size_in_bytes() instead of setting the process-global v8_flags.max_old_space_size flag (unless --max-heap-size is also passed). Workers without an explicit resourceLimits.maxOldGenerationSizeMb continue to inherit the parent isolate's --max-old-space-size (and report that inherited limit on worker.resourceLimits), while workers with an explicit resourceLimits.maxOldGenerationSizeMb or worker execArgv can override it. Fixes: https://github.com/nodejs/node/issues/67014 Refs: https://github.com/nodejs/node/issues/43991 Signed-off-by: Rudolf Meijering --- doc/api/cli.md | 2 +- doc/api/worker_threads.md | 7 ++++-- doc/node-config-schema.json | 4 +++ doc/node.1 | 4 +-- src/api/embed_helpers.cc | 3 +++ src/api/environment.cc | 26 +++++++++++++++----- src/node.cc | 22 ++++++++++++++--- src/node_internals.h | 2 ++ src/node_options.cc | 26 +++++++++++++++++--- src/node_options.h | 2 ++ src/node_worker.cc | 9 +++++++ test/parallel/test-worker-resource-limits.js | 15 +++++++++++ 12 files changed, 105 insertions(+), 17 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 52ea6f3f10e1..deaed8861e47 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -4351,6 +4351,7 @@ one is included in the list below. * `--localstorage-file` * `--max-http-header-size` * `--max-old-space-size-percentage` +* `--max-old-space-size` * `--network-family-autoselection-attempt-timeout` * `--no-addons` * `--no-deprecation` @@ -4463,7 +4464,6 @@ V8 options that are allowed are: * `--interpreted-frames-native-stack` * `--jitless` * `--max-heap-size` -* `--max-old-space-size` * `--max-semi-space-size` * `--perf-basic-prof-only-functions` * `--perf-basic-prof` diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index af572039c8ac..f1a776ae13bc 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -1656,8 +1656,9 @@ changes: including no `ArrayBuffer`s. Even if these limits are set, the process may still abort if it encounters a global out-of-memory situation. * `maxOldGenerationSizeMb` {number} The maximum size of the main heap in - MB. If the command-line argument [`--max-old-space-size`][] is set, it - overrides this setting. + MB. Defaults to the value inherited from the parent thread (including + [`--max-old-space-size`][] or [`--max-old-space-size-percentage`][]). If + [`--max-heap-size`][] is set, it overrides this setting. * `maxYoungGenerationSizeMb` {number} The maximum size of a heap space for recently created objects. If the command-line argument [`--max-semi-space-size`][] is set, it overrides this setting. @@ -2228,7 +2229,9 @@ thread spawned will spawn another until the application crashes. [`'close'` event]: #event-close [`'exit'` event]: #event-exit [`'online'` event]: #event-online +[`--max-heap-size`]: cli.md#--max-heap-size [`--max-old-space-size`]: cli.md#--max-old-space-sizesize-in-mib +[`--max-old-space-size-percentage`]: cli.md#--max-old-space-size-percentagepercentage [`--max-semi-space-size`]: cli.md#--max-semi-space-sizesize-in-mib [`AsyncResource`]: async_hooks.md#class-asyncresource [`Buffer.allocUnsafe()`]: buffer.md#static-method-bufferallocunsafesize-alignment diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json index 8453ca49e7da..e66432a9df53 100644 --- a/doc/node-config-schema.json +++ b/doc/node-config-schema.json @@ -518,6 +518,10 @@ "type": "number", "description": "set the maximum size of HTTP headers (default: 16384 (16KB))" }, + "max-old-space-size": { + "type": "string", + "description": "set V8's max old space size (in MiB)" + }, "max-old-space-size-percentage": { "type": "string", "description": "set V8's max old space size as a percentage of available memory (e.g., '50%'). Takes precedence over --max-old-space-size." diff --git a/doc/node.1 b/doc/node.1 index 5da352d7472b..da55774a8060 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -2361,6 +2361,8 @@ one is included in the list below. .It \fB--max-old-space-size-percentage\fR .It +\fB--max-old-space-size\fR +.It \fB--network-family-autoselection-attempt-timeout\fR .It \fB--no-addons\fR @@ -2574,8 +2576,6 @@ V8 options that are allowed are: .It \fB--max-heap-size\fR .It -\fB--max-old-space-size\fR -.It \fB--max-semi-space-size\fR .It \fB--perf-basic-prof-only-functions\fR diff --git a/src/api/embed_helpers.cc b/src/api/embed_helpers.cc index 4e26befd7471..04609bdbfce3 100644 --- a/src/api/embed_helpers.cc +++ b/src/api/embed_helpers.cc @@ -124,6 +124,9 @@ CommonEnvironmentSetup::CommonEnvironmentSetup( // it will be owned by the snapshot creator and needs to be cleaned up // before serialization. if (flags & Flags::kIsForSnapshotting) { + SetIsolateMaxOldGenerationSize( + ¶ms.constraints, + per_process::cli_options->per_isolate->max_old_space_size_mb); // The isolate must be registered before the SnapshotCreator initializes the // isolate, so that the memory reducer can be initialized. isolate = impl_->isolate = Isolate::Allocate(GetOrCreateIsolateGroup()); diff --git a/src/api/environment.cc b/src/api/environment.cc index 4a7b70168e6d..4422f5747fa2 100644 --- a/src/api/environment.cc +++ b/src/api/environment.cc @@ -207,17 +207,31 @@ void FreeArrayBufferAllocator(ArrayBufferAllocator* allocator) { delete allocator; } +void SetIsolateMaxOldGenerationSize(v8::ResourceConstraints* constraints, + uint64_t max_old_space_size_mb) { + if (max_old_space_size_mb == 0) return; + constexpr size_t kMB = 1024 * 1024; + constraints->set_max_old_generation_size_in_bytes( + static_cast(std::min(max_old_space_size_mb, + SIZE_MAX / kMB)) * kMB); +} + void SetIsolateCreateParamsForNode(Isolate::CreateParams* params) { const uint64_t constrained_memory = uv_get_constrained_memory(); const uint64_t total_memory = constrained_memory > 0 ? std::min(uv_get_total_memory(), constrained_memory) : uv_get_total_memory(); - if (total_memory > 0 && - params->constraints.max_old_generation_size_in_bytes() == 0) { - // V8 defaults to 700MB or 1.4GB on 32 and 64 bit platforms respectively. - // This default is based on browser use-cases. Tell V8 to configure the - // heap based on the actual physical memory. - params->constraints.ConfigureDefaults(total_memory, 0); + if (params->constraints.max_old_generation_size_in_bytes() == 0) { + if (total_memory > 0) { + // V8 defaults to 700MB or 1.4GB on 32 and 64 bit platforms respectively. + // This default is based on browser use-cases. Tell V8 to configure the + // heap based on the actual physical memory. + params->constraints.ConfigureDefaults(total_memory, 0); + } + Mutex::ScopedLock lock(per_process::cli_options_mutex); + SetIsolateMaxOldGenerationSize( + ¶ms->constraints, + per_process::cli_options->per_isolate->max_old_space_size_mb); } #ifdef NODE_ENABLE_VTUNE_PROFILING diff --git a/src/node.cc b/src/node.cc index 6c9b51bfb5e8..7d53acba691a 100644 --- a/src/node.cc +++ b/src/node.cc @@ -765,6 +765,16 @@ static void CheckGlobalProcessTimeoutOptions( per_process::cli_options->CheckProcessTimeoutOptions(errors, argv); } +static bool HasMaxHeapSizeFlag(const std::vector& v8_args) { + return std::ranges::any_of(v8_args | std::views::drop(1), [](std::string a) { + std::ranges::replace(a, '_', '-'); + std::string_view s = a; + if (!s.starts_with('-')) return false; + s.remove_prefix(s.starts_with("--") ? 2 : 1); + return s == "max-heap-size" || s.starts_with("max-heap-size="); + }); +} + static ExitCode ProcessGlobalArgsInternal(std::vector* args, std::vector* exec_args, std::vector* errors, @@ -801,11 +811,17 @@ static ExitCode ProcessGlobalArgsInternal(std::vector* args, return ExitCode::kInvalidCommandLineArgument2; } - if (!per_process::cli_options->per_isolate->max_old_space_size_percentage - .empty()) { + static bool has_max_heap_size_flag = false; + has_max_heap_size_flag |= HasMaxHeapSizeFlag(v8_args); + + // Only hand --max-old-space-size to V8 when --max-heap-size needs it; + // otherwise it's applied per isolate so workers can override it. + if (has_max_heap_size_flag && + per_process::cli_options->per_isolate->max_old_space_size_mb != 0) { v8_args.emplace_back( "--max_old_space_size=" + - per_process::cli_options->per_isolate->max_old_space_size); + std::to_string( + per_process::cli_options->per_isolate->max_old_space_size_mb)); } auto env_opts = per_process::cli_options->per_isolate->per_env; diff --git a/src/node_internals.h b/src/node_internals.h index 6fc29ac89e42..12d9140af2ab 100644 --- a/src/node_internals.h +++ b/src/node_internals.h @@ -415,6 +415,8 @@ class InitializationResultImpl final : public InitializationResult { void SetIsolateMiscHandlers(v8::Isolate* isolate, const IsolateSettings& s); void SetIsolateCreateParamsForNode(v8::Isolate::CreateParams* params); +void SetIsolateMaxOldGenerationSize(v8::ResourceConstraints* constraints, + uint64_t max_old_space_size_mb); #if HAVE_INSPECTOR namespace profiler { diff --git a/src/node_options.cc b/src/node_options.cc index d0e34fd3d176..128019c40aab 100644 --- a/src/node_options.cc +++ b/src/node_options.cc @@ -234,6 +234,21 @@ void PerProcessOptions::CheckProcessTimeoutOptions( } } +void PerIsolateOptions::HandleMaxOldSpaceSize( + std::vector* errors) { + uint64_t parsed_mb = 0; + const char* begin = max_old_space_size.data(); + const char* end = begin + max_old_space_size.size(); + auto [ptr, ec] = std::from_chars(begin, end, parsed_mb); + if (ec != std::errc() || ptr != end) { + errors->push_back("--max-old-space-size must be a valid non-negative " + "integer. Got: " + + max_old_space_size); + return; + } + max_old_space_size_mb = parsed_mb; +} + void PerIsolateOptions::HandleMaxOldSpaceSizePercentage( std::vector* errors, std::string* max_old_space_size_percentage) { @@ -280,12 +295,14 @@ void PerIsolateOptions::HandleMaxOldSpaceSizePercentage( uint64_t memory_mb = available_memory / (1024 * 1024); uint64_t calculated_mb = static_cast(memory_mb * percentage / 100.0); - // Convert back to string - max_old_space_size = std::to_string(calculated_mb); + max_old_space_size_mb = calculated_mb; } void PerIsolateOptions::CheckOptions(std::vector* errors, std::vector* argv) { + if (!max_old_space_size.empty()) { + HandleMaxOldSpaceSize(errors); + } if (!max_old_space_size_percentage.empty()) { HandleMaxOldSpaceSizePercentage(errors, &max_old_space_size_percentage); } @@ -1574,7 +1591,10 @@ PerIsolateOptionsParser::PerIsolateOptionsParser( V8Option{}, kAllowedInEnvvar); AddOption("--max-heap-size", "", V8Option{}, kAllowedInEnvvar); - AddOption("--max-old-space-size", "", V8Option{}, kAllowedInEnvvar); + AddOption("--max-old-space-size", + "set V8's max old space size (in MiB)", + &PerIsolateOptions::max_old_space_size, + kAllowedInEnvvar); AddOption("--max-old-space-size-percentage", "set V8's max old space size as a percentage of available memory " "(e.g., '50%'). Takes precedence over --max-old-space-size.", diff --git a/src/node_options.h b/src/node_options.h index 69d590802311..fd57c8bef5f4 100644 --- a/src/node_options.h +++ b/src/node_options.h @@ -348,6 +348,7 @@ class PerIsolateOptions : public Options { std::string max_old_space_size_percentage; std::string max_old_space_size; + uint64_t max_old_space_size_mb = 0; std::string report_signal = "SIGUSR2"; std::string build_snapshot_config; @@ -362,6 +363,7 @@ class PerIsolateOptions : public Options { inline EnvironmentOptions* get_per_env_options(); void CheckOptions(std::vector* errors, std::vector* argv) override; + void HandleMaxOldSpaceSize(std::vector* errors); void HandleMaxOldSpaceSizePercentage(std::vector* errors, std::string* max_old_space_size); diff --git a/src/node_worker.cc b/src/node_worker.cc index 9c8f215e094e..54bd956082ce 100644 --- a/src/node_worker.cc +++ b/src/node_worker.cc @@ -142,6 +142,8 @@ void Worker::UpdateResourceConstraints(ResourceConstraints* constraints) { constraints->set_max_old_generation_size_in_bytes( static_cast(resource_limits_[kMaxOldGenerationSizeMb] * kMB)); } else { + SetIsolateMaxOldGenerationSize(constraints, + per_isolate_opts_->max_old_space_size_mb); resource_limits_[kMaxOldGenerationSizeMb] = constraints->max_old_generation_size_in_bytes() / kMB; } @@ -575,6 +577,8 @@ void Worker::New(const FunctionCallbackInfo& args) { if (args[1]->IsObject() || args[2]->IsArray()) { per_isolate_opts.reset(new PerIsolateOptions()); + per_isolate_opts->max_old_space_size_mb = + env->isolate_data()->options()->max_old_space_size_mb; HandleEnvOptions(per_isolate_opts->per_env, [&env_vars](const char* name) { return env_vars->Get(name).value_or(""); @@ -614,6 +618,11 @@ void Worker::New(const FunctionCallbackInfo& args) { per_process_opts.get(), kAllowedInEnvvar, &errors); + // Inherit the parent's effective limit; execArgv may still override it. + per_isolate_opts->max_old_space_size_mb = + env->isolate_data()->options()->max_old_space_size_mb; + per_isolate_opts->max_old_space_size.clear(); + per_isolate_opts->max_old_space_size_percentage.clear(); } else { options_parser::Parse(&env_argv, nullptr, diff --git a/test/parallel/test-worker-resource-limits.js b/test/parallel/test-worker-resource-limits.js index f79c31b2a187..86c97a4835f3 100644 --- a/test/parallel/test-worker-resource-limits.js +++ b/test/parallel/test-worker-resource-limits.js @@ -1,3 +1,4 @@ +// Flags: --max-old-space-size=512 'use strict'; const common = require('../common'); const assert = require('assert'); @@ -6,6 +7,20 @@ const { Worker, resourceLimits, isMainThread } = require('worker_threads'); if (isMainThread) { assert.deepStrictEqual(resourceLimits, {}); + const defaultLimitWorker = new Worker( + 'const { parentPort, resourceLimits } = require("worker_threads");' + + 'parentPort.postMessage(resourceLimits.maxOldGenerationSizeMb);', + { eval: true }); + defaultLimitWorker.on('message', common.mustCall((limit) => { + assert.strictEqual(limit, 512); + })); + const execArgvWorker = new Worker( + 'const { parentPort, resourceLimits } = require("worker_threads");' + + 'parentPort.postMessage(resourceLimits.maxOldGenerationSizeMb);', + { eval: true, execArgv: ['--max-old-space-size=128'] }); + execArgvWorker.on('message', common.mustCall((limit) => { + assert.strictEqual(limit, 128); + })); } const testResourceLimits = { From 11ae8f9b3e5e41e8a30b274c802787a4bb06c9ed Mon Sep 17 00:00:00 2001 From: Rudolf Meijering Date: Tue, 17 Nov 2026 16:36:15 +0100 Subject: [PATCH 2/2] doc,src: fix clang-format and markdown link ordering Signed-off-by: Rudolf Meijering --- doc/api/worker_threads.md | 2 +- src/api/environment.cc | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index f1a776ae13bc..9afab2edf40f 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -2230,8 +2230,8 @@ thread spawned will spawn another until the application crashes. [`'exit'` event]: #event-exit [`'online'` event]: #event-online [`--max-heap-size`]: cli.md#--max-heap-size -[`--max-old-space-size`]: cli.md#--max-old-space-sizesize-in-mib [`--max-old-space-size-percentage`]: cli.md#--max-old-space-size-percentagepercentage +[`--max-old-space-size`]: cli.md#--max-old-space-sizesize-in-mib [`--max-semi-space-size`]: cli.md#--max-semi-space-sizesize-in-mib [`AsyncResource`]: async_hooks.md#class-asyncresource [`Buffer.allocUnsafe()`]: buffer.md#static-method-bufferallocunsafesize-alignment diff --git a/src/api/environment.cc b/src/api/environment.cc index 4422f5747fa2..49f53d2ef69c 100644 --- a/src/api/environment.cc +++ b/src/api/environment.cc @@ -212,8 +212,9 @@ void SetIsolateMaxOldGenerationSize(v8::ResourceConstraints* constraints, if (max_old_space_size_mb == 0) return; constexpr size_t kMB = 1024 * 1024; constraints->set_max_old_generation_size_in_bytes( - static_cast(std::min(max_old_space_size_mb, - SIZE_MAX / kMB)) * kMB); + static_cast( + std::min(max_old_space_size_mb, SIZE_MAX / kMB)) * + kMB); } void SetIsolateCreateParamsForNode(Isolate::CreateParams* params) {