src: let embedders supply a builtin code cache without a snapshot by codebytere · Pull Request #65352 · nodejs/node

codebytere · 2026-08-17T12:58:17Z

An embedder that creates its contexts and Environments without Node's snapshot (its own isolate, no EmbedderSnapshotData) compiles every builtin the bootstrap touches from source in each such process, and then serializes a fresh code cache for each of them that only a later worker thread ever reads. This adds a way to hand Node.js a cache built ahead of time, plus a flag to skip the runtime serialization. embedtest's start-to-exit goes from 58 to 39 ms with a supplied cache, and the flag alone saves 6 ms; node itself is unchanged.

embedtest, process start → exit, n=40 interleaved      script: `0`              script: require http, fs/promises,
                                                                                   child_process, url, util, stream
  base → this branch, nothing supplied            57.9 → 58.1 ms   n.s.          76.0 → 76.8 ms   n.s.
  + cache from GenerateBuiltinCodeCache()              → 39.3 ms   −32 %  ***         → 47.3 ms   −38 %  ***
  + kNoHarvestBuiltinCodeCache                         → 51.5 ms   −11 %  ***         → 67.7 ms   −11 %  ***
  + both                                               → 39.5 ms   −32 %  ***         → 46.6 ms   −39 %  ***
node -e 0 / node --no-node-snapshot -e 0, base → branch    24.2 → 23.9 / 59.1 → 58.9 ms, both n.s.

With the supplied cache all 114 functions the bootstrap and NewContext() compile are accepted from it, internal/per_context/* included (NODE_DEBUG_NATIVE=CODE_CACHE).

node::GenerateBuiltinCodeCache(context) compiles every builtin in a context made with node::NewContext() in the kind of isolate the cache is for (same V8, flags and read-only snapshot) and returns id + bytes for a build step to embed.
node::SetBuiltinCodeCache(entries) installs process-wide entries that every BuiltinLoader created afterwards starts with: each Environment's, and the loader NewContext() uses for the per-context scripts. A snapshot's entries still merge on top, so RefreshCodeCache() now merges with insert_or_assign instead of asserting a single call.
ProcessInitializationFlags::kNoHarvestBuiltinCodeCache stops LookupAndCompile() from serializing a cache for builtins compiled without one. The default stays as it is because worker threads start from that harvested cache.

embedtest gets --builtin-code-cache-create <file>, --builtin-code-cache <file> and --no-harvest-builtin-code-cache so the test drives all three through an embedder binary: it generates a cache in one process, checks that another process's bootstrap and per-context scripts compile from it, and that a worker started with and without the flag does and doesn't find a harvested cache.

Tests: the new embedding test and two cctests (RefreshCodeCache merges, the process cache seeds new loaders); embedding, cctest and the default suite pass.

Disclosure: the code, tests, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

nodejs-github-bot · 2026-08-17T12:58:22Z

Review requested:

@nodejs/startup

nodejs-github-bot · 2026-08-17T18:57:20Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75944/

codecov · 2026-08-17T19:00:49Z

Codecov Report

❌ Patch coverage is 93.33333% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.12%. Comparing base (30bff4a) to head (e512f86).
⚠️ Report is 78 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_builtins.cc	92.00%	1 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65352      +/-   ##
==========================================
- Coverage   90.13%   90.12%   -0.02%     
==========================================
  Files         752      752              
  Lines      251568   252370     +802     
  Branches    47270    47454     +184     
==========================================
+ Hits       226759   227438     +679     
- Misses      16168    16255      +87     
- Partials     8641     8677      +36

Files with missing lines	Coverage Δ
src/api/environment.cc	`78.54% <100.00%> (+0.13%)`	⬆️
src/env.cc	`85.65% <100.00%> (+0.16%)`	⬆️
src/node.cc	`76.59% <100.00%> (+0.06%)`	⬆️
src/node.h	`91.48% <ø> (-0.82%)`	⬇️
src/node_builtins.h	`100.00% <ø> (ø)`
src/node_builtins.cc	`77.73% <92.00%> (+1.41%)`	⬆️

... and 81 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-18T14:18:11Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75967/

nodejs-github-bot · 2026-08-20T20:54:47Z

CI: https://ci.nodejs.org/job/node-test-pull-request/76077/

legendecas · 2026-08-20T20:59:23Z

+    ProcessCodeCache& pcc = GetProcessCodeCache();
+    Mutex::ScopedLock lock(pcc.mutex);
+    harvest_code_cache_ = pcc.harvest;
+    if (!pcc.entries.empty()) RefreshCodeCache(pcc.entries);


node/src/env.cc

Lines 868 to 874 in 9f0ce45

if (!is_main_thread()) {

// If this is a Worker thread, we can always safely use the parent's

// Isolate's code cache because of the shared read-only heap.

CHECK_NOT_NULL(isolate_data->worker_context());

builtin_loader()->CopySourceAndCodeCacheReferenceFrom(

isolate_data->worker_context()->env()->builtin_loader());

} else if (isolate_data->snapshot_data() != nullptr) {

A worker env inherits the cached entries from its parent env's built-in loader. With the current PR, a worker copies two code cache maps, at the Environment constructor, and at this BuiltinLoader constructor.

This can an option on node::CreateIsolateData and feed into the parent env, then inherited by workers, with one copy of the cached entries.

Eh, I think it might be worse than my first impression. CopySourceAndCodeCacheReferenceFrom copies a shared_ptr to the BuiltinCodeCache. The parent env might already refreshed the code caches (if they were rejected), and this refershing from ProcessCodeCache might invalidate the latest cache and cache again.

@legendecas the clobbering can't happen as it stands: builtin_loader_ is a member, so its constructor seeds its own fresh map before the Environment constructor body swaps in the parent's shared_ptr for workers; nothing ever refreshes a shared map. you're right that a worker then seeds a map it immediately drops though, and hiding that in the constructor is what made it look dangerous - moved it to an explicit SeedFromProcessCodeCache() for the two loaders that don't inherit (the main-thread env's, ahead of the snapshot merge, and the per-context one), workers just inherit. on hanging it off CreateIsolateData instead: the per-context loader in NewContext() has no IsolateData to read, and that's the loader an embedder can't reach today, so it needs to be process-scoped i think.

Contexts and Environments created from the built-in snapshot get the builtins' code cache from that snapshot. An embedder that bootstraps them from scratch (its own isolate and context, no EmbedderSnapshotData) has no way to provide one: every builtin the bootstrap touches, and the per-context scripts NewContext() runs, are compiled from source in every such process, and each of them then serializes a fresh cache (SaveCodeCache) that only a later worker thread would ever consume. Add a small public API for that case: - node::GenerateBuiltinCodeCache(context) compiles every builtin in a context of the right kind of isolate and returns the caches, for a build step that embeds them. - node::SetBuiltinCodeCache(entries) installs process-wide entries that every BuiltinLoader created afterwards starts with, i.e. each Environment's and the loader for the per-context scripts. Entries a snapshot provides still merge on top (RefreshCodeCache() now merges with insert_or_assign instead of assuming a single call). - ProcessInitializationFlags::kNoHarvestBuiltinCodeCache stops serializing caches for builtins compiled without one, for embedders that supply their own or never create workers. The default is unchanged because worker threads copy the harvested cache. embedtest gains --builtin-code-cache-create, --builtin-code-cache and --no-harvest-builtin-code-cache, and a test that generates a cache in one process, checks that the bootstrap and per-context scripts of another compile with it, and that a worker does or does not find a harvested cache depending on the flag. On x64 Linux embedtest's start-to-exit goes from ~64 to ~44 ms with a supplied cache; not harvesting alone saves ~5 ms on a snapshot-less start and is a no-op with the snapshot. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. labels Aug 17, 2026

jasnell reviewed Aug 17, 2026

View reviewed changes

Comment thread src/node_builtins.cc Outdated

jasnell reviewed Aug 17, 2026

View reviewed changes

Comment thread src/node_builtins.cc Outdated

codebytere force-pushed the embedder/builtin-code-cache-seed branch from 1b99e86 to 136d2ad Compare August 17, 2026 13:25

codebytere requested review from jasnell and joyeecheung August 17, 2026 17:34

jasnell approved these changes Aug 17, 2026

View reviewed changes

codebytere added the request-ci Add this label to start a Jenkins CI on a PR. label Aug 17, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 17, 2026

legendecas reviewed Aug 20, 2026

View reviewed changes

Comment thread test/embedding/test-embedding-builtin-code-cache.js Outdated

codebytere force-pushed the embedder/builtin-code-cache-seed branch from 136d2ad to d33c3df Compare August 20, 2026 20:34

legendecas approved these changes Aug 20, 2026

View reviewed changes

legendecas added semver-minor PRs that contain new features and should be released in the next minor version. request-ci Add this label to start a Jenkins CI on a PR. labels Aug 20, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 20, 2026

legendecas reviewed Aug 20, 2026

View reviewed changes

codebytere force-pushed the embedder/builtin-code-cache-seed branch from d33c3df to e512f86 Compare August 21, 2026 06:06

Navigation Menu

Uh oh!

Uh oh!

src: let embedders supply a builtin code cache without a snapshot - #65352

src: let embedders supply a builtin code cache without a snapshot#65352
codebytere wants to merge 1 commit into
nodejs:mainfrom
codebytere:embedder/builtin-code-cache-seed

codebytere commented Aug 17, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

codecov Bot commented Aug 17, 2026 •

edited

Loading

Uh oh!

nodejs-github-bot commented Aug 18, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 20, 2026

Uh oh!

legendecas Aug 20, 2026 •

edited

Loading

Uh oh!

legendecas Aug 20, 2026

Uh oh!

codebytere Aug 21, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	if (!is_main_thread()) {
	// If this is a Worker thread, we can always safely use the parent's
	// Isolate's code cache because of the shared read-only heap.
	CHECK_NOT_NULL(isolate_data->worker_context());
	builtin_loader()->CopySourceAndCodeCacheReferenceFrom(
	isolate_data->worker_context()->env()->builtin_loader());
	} else if (isolate_data->snapshot_data() != nullptr) {

Uh oh!

Uh oh!

Conversation

codebytere commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 17, 2026

Uh oh!

codecov Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nodejs-github-bot commented Aug 18, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 20, 2026

Uh oh!

legendecas Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

legendecas Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

codebytere Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codebytere commented Aug 17, 2026 •

edited

Loading

codecov Bot commented Aug 17, 2026 •

edited

Loading

legendecas Aug 20, 2026 •

edited

Loading

codebytere Aug 21, 2026 •

edited

Loading