Skip to content

Commit b8d7b77

Browse files
authored
perf: keep memory use down at low thread counts (#1179)
1 parent 060be4c commit b8d7b77

17 files changed

Lines changed: 275 additions & 32 deletions

File tree

‎.changeset/keep-memory-down.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@doc-kit/core': patch
3+
'@doc-kit/generator-react': patch
4+
'@node-core/doc-kit-legacy': patch
5+
---
6+
7+
Builds use less memory, most of all with few threads: each worker's young generation is limited to 96MB, a single thread processes one chunk at a time and lets go of the pages' code before rendering them, and Vite's native bundler gets as many threads as doc-kit and returns the memory it frees. On the Node.js API docs, `--threads 1` now builds with Node.js's `--max-old-space-size=512`, and no longer crashes when `legacy-html` is built alongside other targets.

‎packages/core/src/generators.mjs‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,16 +87,18 @@ const createGenerator = () => {
8787
? createParallelWorker(specifier, generator, pool, configuration)
8888
: Promise.resolve(null);
8989

90-
const result = await generate(dependencyInput, await worker);
91-
90+
// Returned rather than awaited, so this function doesn't hold on to the
91+
// input while the generator runs, and the generator can let it go
92+
return generate(dependencyInput, await worker);
93+
})().then(result => {
9294
// For streaming generators, "Completed" is logged when the cache
9395
// finishes collecting, not here when the generator returns
9496
if (!isAsyncIterable(result)) {
9597
generatorsLogger.debug(`Completed "${name}"`);
9698
}
9799

98100
return result;
99-
})()
101+
})
100102
);
101103
};
102104

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
44

55
import { LogLevel } from '../../logger/constants.mjs';
66
import logger from '../../logger/index.mjs';
7+
import { WORKER_GEN_SIZE, WORKER_HEAP_SIZE } from '../constants.mjs';
78
import createWorkerPool from '../index.mjs';
89

910
const reporterSpecifier = fileURLToPath(
@@ -114,4 +115,17 @@ describe('createWorkerPool', () => {
114115
await pool.destroy();
115116
}
116117
});
118+
119+
it("should limit each worker's old and young generation", async () => {
120+
const pool = createWorkerPool(1);
121+
122+
try {
123+
deepStrictEqual(pool.options.resourceLimits, {
124+
maxOldGenerationSizeMb: WORKER_HEAP_SIZE,
125+
maxYoungGenerationSizeMb: WORKER_GEN_SIZE,
126+
});
127+
} finally {
128+
await pool.destroy();
129+
}
130+
});
117131
});

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,4 +229,32 @@ describe('createParallelWorker', () => {
229229

230230
await rejects(result, /chunk failed/);
231231
});
232+
233+
it('should process one chunk at a time, in order, with a single thread', async () => {
234+
let running = 0;
235+
let mostRunning = 0;
236+
237+
const generator = {
238+
name: 'sequential',
239+
async processChunk(items, indices) {
240+
mostRunning = Math.max(mostRunning, ++running);
241+
242+
await new Promise(resolve => setImmediate(resolve));
243+
244+
running--;
245+
246+
return indices.map(index => items[index]);
247+
},
248+
};
249+
250+
const worker = createParallelWorker('sequential', generator, null, {
251+
threads: 1,
252+
chunkSize: 2,
253+
});
254+
255+
const chunks = await collectChunks(worker.stream([1, 2, 3, 4, 5], {}));
256+
257+
strictEqual(mostRunning, 1);
258+
deepStrictEqual(chunks, [[1, 2], [3, 4], [5]]);
259+
});
232260
});

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
'use strict';
22

3+
/**
4+
* The default `threads` ceiling. Each worker holds a heap of its own, with the
5+
* libraries and the pages it is working on, so past a few threads memory, not
6+
* CPU, is what runs out. `--threads` raises it.
7+
*/
8+
export const DEFAULT_MAX_THREADS = 4;
9+
310
/**
411
* The heap size limit of each worker thread (V8's old space), in MB. V8 lets a
512
* heap grow to several times its live data before collecting it, the more the
@@ -8,3 +15,10 @@
815
* `--max-old-space-size` replaces it.
916
*/
1017
export const WORKER_HEAP_SIZE = 512;
18+
19+
/**
20+
* The young generation size limit of each worker thread, in MB. V8 sizes it
21+
* from the machine's memory, as if each worker were the only one, so it made up
22+
* over half of a worker's heap. Node.js's `--max-semi-space-size` replaces it.
23+
*/
24+
export const WORKER_GEN_SIZE = 96;

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import Piscina from 'piscina';
22

33
import logger from '#logger/index.mjs';
44

5-
import { WORKER_HEAP_SIZE } from './constants.mjs';
5+
import { WORKER_HEAP_SIZE, WORKER_GEN_SIZE } from './constants.mjs';
66

77
const poolLogger = logger.child('WorkerPool');
88

@@ -27,7 +27,10 @@ export default function createWorkerPool(threads) {
2727
// A worker idle for 250ms ends, so its heap is gone during a long stretch
2828
// of work on the main thread, such as bundling the site
2929
idleTimeout: 250,
30-
resourceLimits: { maxOldGenerationSizeMb: WORKER_HEAP_SIZE },
30+
resourceLimits: {
31+
maxOldGenerationSizeMb: WORKER_HEAP_SIZE,
32+
maxYoungGenerationSizeMb: WORKER_GEN_SIZE,
33+
},
3134
recordTiming: false,
3235
workerData: { logLevel: logger.getLogLevel() },
3336
});

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

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -96,17 +96,22 @@ export default function createParallelWorker(
9696
{ generator: name, chunks: chunks.length, chunkSize, threads }
9797
);
9898

99-
const runInOneGo = threads <= 1 || items.length <= 2;
99+
// On this thread, one chunk at a time, so their work isn't all held at once
100+
if (threads <= 1 || items.length <= 2) {
101+
for (const indices of chunks) {
102+
yield await generator.processChunk(items, indices, extra);
103+
}
104+
105+
return;
106+
}
100107

101108
// Start every chunk immediately, but emit results in submission order.
102109
// Handle errors as each task settles so a later failure cannot become an
103110
// unhandled rejection while earlier chunks are still running.
104111
const tasks = chunks.map(indices => {
105-
const task = runInOneGo
106-
? generator.processChunk(items, indices, extra)
107-
: pool.run(
108-
createTask(items, indices, extra, configuration, specifier, name)
109-
);
112+
const task = pool.run(
113+
createTask(items, indices, extra, configuration, specifier, name)
114+
);
110115

111116
return task.then(
112117
result => ({ result }),

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

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,5 @@
11
'use strict';
22

3-
/**
4-
* The default `threads` ceiling. Each worker holds a heap of its own, with the
5-
* libraries and the pages it is working on, so past a few threads memory, not
6-
* CPU, is what runs out. `--threads` raises it.
7-
*/
8-
export const DEFAULT_MAX_THREADS = 4;
9-
103
/**
114
* The default number of items each worker task processes.
125
*/

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

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,8 @@ import {
2222
import { resolveMarkdown } from '#utils/markdown/plugins.mjs';
2323
import { deepMerge } from '#utils/misc.mjs';
2424

25-
import {
26-
DEFAULT_CHUNK_SIZE,
27-
DEFAULT_MAX_THREADS,
28-
DEFAULT_OUTPUT_DIRECTORY,
29-
} from './constants.mjs';
25+
import { DEFAULT_MAX_THREADS } from '../../threading/constants.mjs';
26+
import { DEFAULT_CHUNK_SIZE, DEFAULT_OUTPUT_DIRECTORY } from './constants.mjs';
3027

3128
const configExplorer = cosmiconfig('doc-kit');
3229

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import assert from 'node:assert/strict';
2+
import { describe, it } from 'node:test';
3+
4+
import { loadGenerator } from '@doc-kit/core/generators/loader.mjs';
5+
import { setConfig } from '@doc-kit/core/utils/configuration/index.mjs';
6+
import { loadMarkdownPlugins } from '@doc-kit/core/utils/markdown/plugins.mjs';
7+
8+
import { processChunk } from '../generate.mjs';
9+
10+
await loadMarkdownPlugins(
11+
await loadGenerator(import.meta.resolve('../index.mjs'))
12+
);
13+
14+
const createEntry = (api, name) => {
15+
const heading = {
16+
type: 'heading',
17+
depth: 1,
18+
children: [{ type: 'text', value: name }],
19+
data: { name, text: name, slug: api, type: 'module' },
20+
};
21+
22+
return {
23+
api,
24+
path: `/${api}`,
25+
heading,
26+
stability: null,
27+
content: {
28+
type: 'root',
29+
children: [
30+
heading,
31+
{
32+
type: 'paragraph',
33+
children: [{ type: 'text', value: `${name} body` }],
34+
},
35+
],
36+
},
37+
};
38+
};
39+
40+
describe('legacy-html processChunk', () => {
41+
it('does not change its input on the main thread', async () => {
42+
await setConfig({ target: ['legacy-html'] });
43+
44+
const fs = createEntry('fs', 'File system');
45+
const before = structuredClone(fs);
46+
47+
const [page] = await processChunk(
48+
[{ head: fs, nodes: [fs], headNodes: [fs] }],
49+
[0],
50+
'<a class="nav-fs" href="fs.html">File system</a>'
51+
);
52+
53+
assert.match(page.content, /File system body/);
54+
assert.deepEqual(fs, before);
55+
});
56+
});

0 commit comments

Comments
 (0)