Skip to content

Commit 2f4ddf6

Browse files
committed
perf(core): limit each worker's heap, by default just under 2GB
V8 lets a heap whose limit is 2GB or more grow to up to four times its live data before collecting it, and on a machine with plenty of memory every worker's limit is 4GB, so each held several times what it used. Below 2GB, a heap only grows to about twice its live data. `workerHeapSize` (`--worker-heap-size`) sets each worker's old space limit, in MB, like `threads` sets their number. It defaults to the limit V8 gives this process, at most `DEFAULT_MAX_WORKER_HEAP_SIZE` (2047): a machine with less memory keeps the smaller limit V8 picks for it. An explicit `--max-old-space-size` still wins, as V8 prefers it. On Node core's build (4 threads), the peak goes from 2.73GB to 2.39GB on Node 26 and from 2.90GB to 2.73GB on Node 24. Lower limits gain little more: 2.29GB at 1536MB, 2.30GB at 768MB. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e6a5e49 commit 2f4ddf6

11 files changed

Lines changed: 122 additions & 20 deletions

File tree

‎docs/cli.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,6 @@ Runs the generators and writes their output. Requires a `target` and an
3939
- `--type-map <url>` {string} Type map URL or path (custom type-name → URL
4040
links).
4141
- `-p, --threads <n>` {number} Worker threads to use (minimum 1).
42+
- `--worker-heap-size <mb>` {number} Heap size limit of each worker thread, in
43+
MB (minimum 1).
4244
- `--chunk-size <n>` {number} Items per worker thread (minimum 1).

‎docs/configuration.md‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,10 @@ Top-level, alongside `target` and `global`:
135135

136136
- `threads` {number} Worker threads used for generation. Defaults to your
137137
CPU count.
138+
- `workerHeapSize` {number} Heap size limit of each worker thread (V8's old
139+
space), in MB. Defaults to V8's own limit, at most `2047`: from 2GB up, V8
140+
lets a heap grow to four times its live data before collecting it, and only
141+
to about twice below that.
138142
- `chunkSize` {number} Items processed per worker thread. **Default:** `10`.
139143

140144
## Generator options
@@ -262,17 +266,18 @@ precedence):
262266

263267
CLI options map to configuration properties:
264268

265-
| CLI Option | Config Property | Example |
266-
| ---------------------- | ------------------ | ------------------------- |
267-
| `--input <path>` | `global.input` | `--input src/` |
268-
| `--output <path>` | `global.output` | `--output dist/` |
269-
| `--ignore <pattern>` | `global.ignore[]` | `--ignore test/` |
270-
| `--minify` | `global.minify` | `--minify` |
271-
| `--git-ref <ref>` | `global.ref` | `--git-ref v20.0.0` |
272-
| `--version <version>` | `global.version` | `--version 20.0.0` |
273-
| `--changelog <url>` | `global.changelog` | `--changelog https://...` |
274-
| `--index <url>` | `global.index` | `--index file://...` |
275-
| `--type-map <map>` | `metadata.typeMap` | `--type-map file://...` |
276-
| `--target <generator>` | `target` | `--target json` |
277-
| `--threads <n>` | `threads` | `--threads 4` |
278-
| `--chunk-size <n>` | `chunkSize` | `--chunk-size 10` |
269+
| CLI Option | Config Property | Example |
270+
| ------------------------- | ------------------ | ------------------------- |
271+
| `--input <path>` | `global.input` | `--input src/` |
272+
| `--output <path>` | `global.output` | `--output dist/` |
273+
| `--ignore <pattern>` | `global.ignore[]` | `--ignore test/` |
274+
| `--minify` | `global.minify` | `--minify` |
275+
| `--git-ref <ref>` | `global.ref` | `--git-ref v20.0.0` |
276+
| `--version <version>` | `global.version` | `--version 20.0.0` |
277+
| `--changelog <url>` | `global.changelog` | `--changelog https://...` |
278+
| `--index <url>` | `global.index` | `--index file://...` |
279+
| `--type-map <map>` | `metadata.typeMap` | `--type-map file://...` |
280+
| `--target <generator>` | `target` | `--target json` |
281+
| `--threads <n>` | `threads` | `--threads 4` |
282+
| `--worker-heap-size <mb>` | `workerHeapSize` | `--worker-heap-size 1024` |
283+
| `--chunk-size <n>` | `chunkSize` | `--chunk-size 10` |

‎packages/cli/bin/commands/generate.mjs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ const { runGenerators } = createGenerator();
1818
* @property {string[]} ignore
1919
* @property {string} output
2020
* @property {number} threads
21+
* @property {number} workerHeapSize
2122
* @property {number} chunkSize
2223
* @property {string} version
2324
* @property {string} changelog
@@ -53,6 +54,12 @@ export default new Command('generate')
5354
'Number of threads to use (minimum: 1)'
5455
)
5556
)
57+
.addOption(
58+
new Option(
59+
'--worker-heap-size <mb>',
60+
'Heap size limit of each worker thread, in MB (minimum: 1)'
61+
)
62+
)
5663
.addOption(
5764
new Option(
5865
'--chunk-size <number>',

‎packages/core/src/generators.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ const createGenerator = () => {
107107
* @returns {Promise<unknown[]>} Results of all requested generators
108108
*/
109109
const runGenerators = async configuration => {
110-
const { target, threads } = configuration;
110+
const { target, threads, workerHeapSize } = configuration;
111111

112112
// Resolve shorthand names and load the full dependency closure up front,
113113
// so scheduling below is fully synchronous.
@@ -132,7 +132,7 @@ const createGenerator = () => {
132132
cache.populateConsumerCounts(targets, specifier => inputOf.get(specifier));
133133

134134
// Create worker pool
135-
pool = createWorkerPool(threads);
135+
pool = createWorkerPool(threads, workerHeapSize);
136136

137137
// Schedule all generators
138138
for (const specifier of targets) {
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
import { getHeapStatistics } from 'node:v8';
2+
3+
/**
4+
* Test generator that reports the heap limit of the worker it runs in, so the
5+
* worker pool's resource limits can be asserted.
6+
*
7+
* @type {GeneratorMetadata<unknown, number[]>}
8+
*/
9+
export default {
10+
name: 'heap-limit-reporter',
11+
version: '1.0.0',
12+
description: 'Reports the heap limit of the worker it runs in',
13+
dependsOn: 'ast',
14+
processChunk: async (_input, itemIndices) =>
15+
itemIndices.map(() => getHeapStatistics().heap_size_limit),
16+
async generate() {
17+
return [getHeapStatistics().heap_size_limit];
18+
},
19+
};

‎packages/core/src/threading/__tests__/index.test.mjs‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { deepStrictEqual, strictEqual } from 'node:assert';
1+
import { deepStrictEqual, ok, strictEqual } from 'node:assert';
22
import { describe, it } from 'node:test';
33
import { fileURLToPath } from 'node:url';
44

@@ -14,6 +14,10 @@ const pluginsReporterSpecifier = fileURLToPath(
1414
import.meta.resolve('./fixtures/markdown-plugins-reporter.mjs')
1515
);
1616

17+
const heapLimitReporter = fileURLToPath(
18+
import.meta.resolve('./fixtures/heap-limit-reporter.mjs')
19+
);
20+
1721
/**
1822
* Runs a function with the logger temporarily set to the given level.
1923
*
@@ -114,4 +118,24 @@ describe('createWorkerPool', () => {
114118
await pool.destroy();
115119
}
116120
});
121+
122+
it("limits each worker's heap to the given size", async () => {
123+
const pool = createWorkerPool(1, 512);
124+
125+
try {
126+
const [workerLimit] = await pool.run({
127+
generatorSpecifier: heapLimitReporter,
128+
input: [null],
129+
itemIndices: [0],
130+
extra: {},
131+
configuration: {},
132+
});
133+
134+
strictEqual(pool.options.resourceLimits.maxOldGenerationSizeMb, 512);
135+
// Its old space, plus a young generation of a few dozen MB
136+
ok(workerLimit < 1024 ** 3);
137+
} finally {
138+
await pool.destroy();
139+
}
140+
});
117141
});

‎packages/core/src/threading/index.mjs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,13 @@ const workerScript = import.meta.resolve('./chunk-worker.mjs');
1010
* Creates a Piscina worker pool for parallel processing.
1111
*
1212
* @param {number} threads - Maximum number of worker threads
13+
* @param {number} heapSize - Each worker's heap size limit (old space), in MB
1314
* @returns {import('piscina').Piscina} Configured Piscina instance
1415
*/
15-
export default function createWorkerPool(threads) {
16+
export default function createWorkerPool(threads, heapSize) {
1617
poolLogger.debug(`WorkerPool initialized`, {
1718
threads,
19+
heapSize,
1820
workerScript,
1921
});
2022

@@ -23,6 +25,7 @@ export default function createWorkerPool(threads) {
2325
minThreads: 0,
2426
maxThreads: threads,
2527
idleTimeout: 1_000,
28+
resourceLimits: { maxOldGenerationSizeMb: heapSize },
2629
workerData: { logLevel: logger.getLogLevel() },
2730
});
2831
}

‎packages/core/src/utils/configuration/__tests__/index.test.mjs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@ import { tmpdir } from 'node:os';
44
import { join } from 'node:path';
55
import { describe, it, mock, beforeEach } from 'node:test';
66
import { pathToFileURL } from 'node:url';
7+
import { getHeapStatistics } from 'node:v8';
78

89
import logger from '../../../logger/index.mjs';
10+
import { DEFAULT_MAX_WORKER_HEAP_SIZE } from '../constants.mjs';
911

1012
// Mock dependencies
1113
const mockParseChangelog = mock.fn(async changelog => [changelog]);
@@ -211,6 +213,7 @@ describe('config.mjs', () => {
211213
typeMap: { String: 'string' },
212214
target: 'json',
213215
threads: 4,
216+
workerHeapSize: 1024,
214217
chunkSize: 5,
215218
};
216219

@@ -230,6 +233,7 @@ describe('config.mjs', () => {
230233
metadata: { typeMap: { String: 'string' } },
231234
target: 'json',
232235
threads: 4,
236+
workerHeapSize: 1024,
233237
chunkSize: 5,
234238
});
235239
});
@@ -330,13 +334,27 @@ describe('config.mjs', () => {
330334
it('should enforce minimum constraints', async () => {
331335
const config = await createRunConfiguration({
332336
threads: -5,
337+
workerHeapSize: 0,
333338
chunkSize: 0,
334339
});
335340

336341
assert.strictEqual(config.threads, 1);
342+
assert.strictEqual(config.workerHeapSize, 1);
337343
assert.strictEqual(config.chunkSize, 1);
338344
});
339345

346+
it("should default the worker heap size to V8's limit, at most just under 2GB", async () => {
347+
const config = await createRunConfiguration({ version: '20.0.0' });
348+
349+
assert.strictEqual(
350+
config.workerHeapSize,
351+
Math.min(
352+
Math.floor(getHeapStatistics().heap_size_limit / 1024 ** 2),
353+
DEFAULT_MAX_WORKER_HEAP_SIZE
354+
)
355+
);
356+
});
357+
340358
it('should work without config file', async () => {
341359
const config = await createRunConfiguration({
342360
version: '20.0.0',

‎packages/core/src/utils/configuration/constants.mjs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@
77
*/
88
export const DEFAULT_MAX_THREADS = 4;
99

10+
/**
11+
* The default `workerHeapSize` ceiling, in MB. V8 lets a heap whose limit is
12+
* 2GB or more grow to up to four times its live data before collecting it,
13+
* and on a machine with plenty of memory that limit is 4GB, so every worker
14+
* held several times what it was using. Just under 2GB, a heap only grows to
15+
* about twice its live data. `--worker-heap-size` raises it.
16+
*/
17+
export const DEFAULT_MAX_WORKER_HEAP_SIZE = 2047;
18+
1019
/**
1120
* The default number of items each worker task processes.
1221
*/

‎packages/core/src/utils/configuration/index.mjs‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { readFileSync } from 'node:fs';
22
import { cpus } from 'node:os';
33
import { fileURLToPath } from 'node:url';
4+
import { getHeapStatistics } from 'node:v8';
45
import { isMainThread } from 'node:worker_threads';
56

67
import { cosmiconfig } from 'cosmiconfig';
@@ -22,7 +23,11 @@ import {
2223
import { resolveMarkdown } from '#utils/markdown/plugins.mjs';
2324
import { deepMerge } from '#utils/misc.mjs';
2425

25-
import { DEFAULT_CHUNK_SIZE, DEFAULT_MAX_THREADS } from './constants.mjs';
26+
import {
27+
DEFAULT_CHUNK_SIZE,
28+
DEFAULT_MAX_THREADS,
29+
DEFAULT_MAX_WORKER_HEAP_SIZE,
30+
} from './constants.mjs';
2631

2732
const configExplorer = cosmiconfig('doc-kit');
2833

@@ -79,6 +84,11 @@ export const getDefaultConfig = (generators, config) =>
7984
process.arch === 'riscv64'
8085
? 1
8186
: Math.min(cpus().length, DEFAULT_MAX_THREADS),
87+
// No more than V8 gives this process: less on a machine with less memory
88+
workerHeapSize: Math.min(
89+
Math.floor(getHeapStatistics().heap_size_limit / 1024 ** 2),
90+
DEFAULT_MAX_WORKER_HEAP_SIZE
91+
),
8292
chunkSize: DEFAULT_CHUNK_SIZE,
8393
})
8494
);
@@ -226,6 +236,7 @@ export const createConfigFromCLIOptions = options => ({
226236
},
227237
target: options.target,
228238
threads: options.threads,
239+
workerHeapSize: options.workerHeapSize,
229240
chunkSize: options.chunkSize,
230241
});
231242

@@ -250,7 +261,7 @@ export const assertRunnableOptions = config => {
250261
/**
251262
* Creates a complete run configuration by merging config file, user options, and defaults.
252263
* Processes and validates configuration values including version coercion, changelog parsing,
253-
* and constraint enforcement for threads and chunk size.
264+
* and constraint enforcement for threads, worker heap size and chunk size.
254265
*
255266
* @param {import('../../../bin/commands/generate.mjs').CLIOptions} options - User-provided configuration options
256267
* @returns {Promise<import('./types').Configuration>} The configuration
@@ -275,6 +286,7 @@ export const createRunConfiguration = async options => {
275286

276287
// These need to be coerced
277288
merged.threads = Math.max(merged.threads, 1);
289+
merged.workerHeapSize = Math.max(merged.workerHeapSize, 1);
278290
merged.chunkSize = Math.max(merged.chunkSize, 1);
279291

280292
if (process.arch === 'riscv64' && merged.threads > 1) {

0 commit comments

Comments
 (0)