Skip to content

module: implement NODE_COMPILE_CACHE for automatic on-disk code caching #52535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
joyeecheung wants to merge 3 commits into from
Closed

module: implement NODE_COMPILE_CACHE for automatic on-disk code caching #52535

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a65d01d
deps: V8: cherry-pick cd10ad7cdbe5
joyeecheung Apr 14, 2024
f7806b3
module: implement NODE_COMPILE_CACHE for automatic on-disk code caching
joyeecheung Feb 29, 2024
b45062b
fixup! module: implement NODE_COMPILE_CACHE for automatic on-disk cod…
joyeecheung Apr 16, 2024
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
29 changes: 29 additions & 0 deletions doc/api/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2486,6 +2486,34 @@ Any other value will result in colorized output being disabled.
[`NO_COLOR`][] is an alias for `NODE_DISABLE_COLORS`. The value of the
environment variable is arbitrary.

### `NODE_COMPILE_CACHE=dir`

<!-- YAML
added: REPLACEME
-->

> Stability: 1.1 - Active Development

When set, whenever Node.js compiles a CommonJS or a ECMAScript Module,
Copy link
Copy Markdown
Member

@benjamingr benjamingr Apr 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description is very technical - I would use more layman terms for the first paragraph.

Copy link
Copy Markdown
Member Author

@joyeecheung joyeecheung Apr 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have specific suggestions? I don't want to make it sound too magical to avoid false advertisement.

Copy link
Copy Markdown
Member

@benjamingr benjamingr Apr 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'll do a follow up PR after this lands to not hold it but ideally something that focuses more on what it does and not the technical implementation

it will use on-disk [V8 code cache][] persisted in the specified directory
to speed up the compilation. This may slow down the first load of a
module graph, but subsequent loads of the same module graph may get
a significant speedup if the contents of the modules do not change.

To clean up the generated code cache, simply remove the directory.
It will be recreated the next time the same directory is used for
`NODE_COMPILE_CACHE`.

Compilation cache generated by one version of Node.js may not be used
by a different version of Node.js. Cache generated by different versions
of Node.js will be stored separately if the same directory is used
to persist the cache, so they can co-exist.

Caveat: currently when using this with [V8 JavaScript code coverage][], the
Copy link
Copy Markdown
Member Author

@joyeecheung joyeecheung Apr 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When enabling NODE_COMPILE_CACHE and running tools/test.py parallel locally, three tests would fail:

Failed tests:
out/Release/node /Users/joyee/projects/node/test/parallel/test-runner-coverage.js
out/Release/node /Users/joyee/projects/node/test/parallel/test-runner-output.mjs
out/Release/node /Users/joyee/projects/node/test/parallel/test-v8-coverage.js

The failed tests are all related to less precise coverage which is currently a known caveat of code cache + v8 native coverage collection (e.g. see #51672). So I just documented that a bit in the docs that users should not use the two together for now. I could spare some time later to fix it in V8, but I don't think it's a blocker for this PR because this feature is currently opt-in. User-land code caching can run into this problem too, and it's technically a V8 bug.

coverage being collected by V8 may be less precise in functions that are
deserialized from the code cache. It's recommended to turn this off when
running tests to generate precise coverage.

### `NODE_DEBUG=module[,…]`

<!-- YAML
Expand Down Expand Up @@ -3130,6 +3158,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
[Source Map]: https://sourcemaps.info/spec.html
[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
[V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
[V8 code cache]: https://v8.dev/blog/code-caching-for-devs
[Web Crypto API]: webcrypto.md
[`"type"`]: packages.md#type
[`--allow-child-process`]: #--allow-child-process
Expand Down
2 changes: 2 additions & 0 deletions node.gyp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
'src/base_object.cc',
'src/cares_wrap.cc',
'src/cleanup_queue.cc',
'src/compile_cache.cc',
'src/connect_wrap.cc',
'src/connection_wrap.cc',
'src/dataqueue/queue.cc',
Expand Down Expand Up @@ -190,6 +191,7 @@
'src/callback_queue-inl.h',
'src/cleanup_queue.h',
'src/cleanup_queue-inl.h',
'src/compile_cache.h',
'src/connect_wrap.h',
'src/connection_wrap.h',
'src/dataqueue/queue.h',
Expand Down
1 change: 1 addition & 0 deletions src/api/environment.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,6 +546,7 @@ MaybeLocal<Value> LoadEnvironment(Environment* env,
if (preload) {
env->set_embedder_preload(std::move(preload));
}
env->InitializeCompileCache();

return StartExecution(env, cb);
}
Expand Down
Loading
⚡