Skip to content

Commit

Permalink
module: implement NODE_COMPILE_CACHE for automatic on-disk code caching
Browse files Browse the repository at this point in the history
This patch implements automatic on-disk code caching that can be enabled
via an environment variable NODE_COMPILE_CACHE.

When set, whenever Node.js compiles a CommonJS or a ECMAScript Module,
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.
Locally, this speeds up loading of test/fixtures/snapshot/typescript.js
from ~130ms to ~80ms.

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
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.

Implementation details:

There is one cache file per module on disk. The directory layout
is:

- Compile cache directory (from NODE_COMPILE_CACHE)
  - 8b23c8fe: CRC32 hash of CachedDataVersionTag + NODE_VERESION
  - 2ea3424d:
     - 10860e5a: CRC32 hash of filename + module type
     - 431e9adc: ...
     - ...

Inside the cache file, there is a header followed by the actual
cache content:

```
[uint32_t] code size
[uint32_t] code hash
[uint32_t] cache size
[uint32_t] cache hash
... compile cache content ...
```

When reading the cache file, we'll also check if the code size
and code hash match the code that the module loader is loading
and whether the cache size and cache hash match the file content
read. If they don't match, or if V8 rejects the cache passed,
we'll ignore the mismatch cache, and regenerate the cache after
compilation succeeds and rewrite it to disk.
  • Loading branch information
joyeecheung committed Apr 15, 2024
1 parent a65d01d commit f7806b3
Show file tree
Hide file tree
Showing 22 changed files with 962 additions and 10 deletions.
29 changes: 29 additions & 0 deletions doc/api/cli.md
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,
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
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
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
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

0 comments on commit f7806b3

Please sign in to comment.