Skip to content
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.

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

src: add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE #54501

Merged
merged 6 commits into from
Aug 28, 2024

Conversation

joyeecheung
Copy link
Member

@joyeecheung joyeecheung commented Aug 22, 2024

Text for releasers:

This adds a new API module.enableCompileCache() that can be used to enable on-disk code caching of all modules loaded after this API is called. Previously this could only be enabled by the NODE_COMPILE_CACHE environment variable, so it could only set by end-users. This API allows tooling and library authors to enable caching of their own code. This is a built-in alternative to the v8-compile-cache/v8-compile-cache-lib packages, but have better performance and supports ESM.

In addition this adds module.getCompileCacheDir() to query the status of the compile cache, and a NODE_DISABLE_COMPILE_CACHE environment variable to disable the code cache. This serves as an escape hatch for end users to avoid unexpected/undesired effects of the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without a specified directory, Node.js will use the value of the NODE_COMPILE_CACHE environment variable if it's set, or defaults to path.join(os.tmpdir(), 'node-compile-cache') otherwise. Therefore it's recommended for tools to call this method without a directory argument to allow overrides.

Fixes: #53639

This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.
@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/loaders

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Aug 22, 2024
Copy link
Member

@benjamingr benjamingr left a comment

Choose a reason for hiding this comment

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

LGTM

@jakebailey
Copy link

I put together microsoft/TypeScript#59720 to enable this in TypeScript; the results are as expected:

Benchmark 1: ~/work/node/out/Release/node ./built/local/_tsc.js --version
  Time (mean ± σ):     120.5 ms ±   1.7 ms    [User: 108.6 ms, System: 11.2 ms]
  Range (min … max):   117.5 ms … 129.1 ms    100 runs
 
Benchmark 2: ~/work/node/out/Release/node ./built/local/tsc.js --version
  Time (mean ± σ):      51.8 ms ±   1.0 ms    [User: 42.3 ms, System: 9.0 ms]
  Range (min … max):    50.4 ms …  56.6 ms    100 runs
 
Summary
  '~/work/node/out/Release/node ./built/local/tsc.js --version' ran
    2.33 ± 0.06 times faster than '~/work/node/out/Release/node ./built/local/_tsc.js --version'
Benchmark 1: echo '{"seq": 1, "command": "status"}' | ~/work/node/out/Release/node ./built/local/_tsserver.js --disableAutomaticTypingAcquisition
  Time (mean ± σ):     192.3 ms ±   2.5 ms    [User: 178.3 ms, System: 19.8 ms]
  Range (min … max):   188.1 ms … 201.1 ms    100 runs
 
Benchmark 2: echo '{"seq": 1, "command": "status"}' | ~/work/node/out/Release/node ./built/local/tsserver.js --disableAutomaticTypingAcquisition
  Time (mean ± σ):      84.6 ms ±   1.1 ms    [User: 76.5 ms, System: 14.5 ms]
  Range (min … max):    82.6 ms …  88.6 ms    100 runs
 
Summary
  'echo '{"seq": 1, "command": "status"}' | ~/work/node/out/Release/node ./built/local/tsserver.js --disableAutomaticTypingAcquisition' ran
    2.27 ± 0.04 times faster than 'echo '{"seq": 1, "command": "status"}' | ~/work/node/out/Release/node ./built/local/_tsserver.js --disableAutomaticTypingAcquisition'

Copy link

codecov bot commented Aug 22, 2024

Codecov Report

Attention: Patch coverage is 98.18182% with 2 lines in your changes missing coverage. Please review.

Project coverage is 87.34%. Comparing base (cc26951) to head (73c03b1).
Report is 354 commits behind head on main.

Files with missing lines Patch % Lines
src/compile_cache.cc 75.00% 1 Missing ⚠️
src/node_modules.cc 97.22% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@           Coverage Diff            @@
##             main   #54501    +/-   ##
========================================
  Coverage   87.34%   87.34%            
========================================
  Files         649      649            
  Lines      182544   182666   +122     
  Branches    35030    35042    +12     
========================================
+ Hits       159445   159555   +110     
- Misses      16372    16387    +15     
+ Partials     6727     6724     -3     
Files with missing lines Coverage Δ
lib/internal/modules/helpers.js 97.85% <100.00%> (+0.28%) ⬆️
lib/module.js 100.00% <100.00%> (ø)
src/compile_cache.h 100.00% <ø> (+25.00%) ⬆️
src/env.cc 85.48% <100.00%> (+0.32%) ⬆️
src/compile_cache.cc 80.00% <75.00%> (ø)
src/node_modules.cc 76.97% <97.22%> (+2.07%) ⬆️

... and 57 files with indirect coverage changes

@jakebailey
Copy link

jakebailey commented Aug 22, 2024

For fun, this is eslint (with enablecompileCache added to bin/eslint.js:

Benchmark 1: NODE_DISABLE_COMPILE_CACHE=true ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --version
  Time (mean ± σ):     129.9 ms ±   7.8 ms    [User: 128.6 ms, System: 17.4 ms]
  Range (min … max):   126.1 ms … 204.6 ms    100 runs
 
  Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet PC without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.
 
Benchmark 2: ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --version
  Time (mean ± σ):     105.5 ms ±   1.8 ms    [User: 103.3 ms, System: 18.6 ms]
  Range (min … max):   101.7 ms … 114.5 ms    100 runs
 
Summary
  '~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --version' ran
    1.23 ± 0.08 times faster than 'NODE_DISABLE_COMPILE_CACHE=true ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --version'
Benchmark 1: NODE_DISABLE_COMPILE_CACHE=true ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --print-config ./src/compiler/debug.ts
  Time (mean ± σ):     791.6 ms ±   6.2 ms    [User: 987.2 ms, System: 86.3 ms]
  Range (min … max):   779.1 ms … 811.3 ms    100 runs
 
Benchmark 2: ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --print-config ./src/compiler/debug.ts
  Time (mean ± σ):     595.0 ms ±   6.4 ms    [User: 786.4 ms, System: 89.5 ms]
  Range (min … max):   583.7 ms … 621.3 ms    100 runs
 
Summary
  '~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --print-config ./src/compiler/debug.ts' ran
    1.33 ± 0.02 times faster than 'NODE_DISABLE_COMPILE_CACHE=true ~/work/node/out/Release/node ./node_modules/eslint/bin/eslint.js --print-config ./src/compiler/debug.ts'

@richardlau richardlau added the semver-minor PRs that contain new features and should be released in the next minor version. label Aug 22, 2024
doc/api/cli.md Outdated Show resolved Hide resolved
doc/api/cli.md Outdated Show resolved Hide resolved
doc/api/module.md Outdated Show resolved Hide resolved
@joyeecheung joyeecheung added the request-ci Add this label to start a Jenkins CI on a PR. label Aug 25, 2024
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Aug 25, 2024
@nodejs-github-bot
Copy link
Collaborator

@nodejs-github-bot
Copy link
Collaborator

@aduh95 aduh95 added the commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. label Aug 28, 2024
@nodejs-github-bot nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 28, 2024
@nodejs-github-bot nodejs-github-bot merged commit ff5ef70 into nodejs:main Aug 28, 2024
61 checks passed
@nodejs-github-bot
Copy link
Collaborator

Landed in ff5ef70

@joyeecheung joyeecheung added the notable-change PRs with changes that should be highlighted in changelogs. label Aug 29, 2024
Copy link
Contributor

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @joyeecheung.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

RafaelGSS pushed a commit that referenced this pull request Aug 30, 2024
This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.

PR-URL: #54501
Fixes: #53639
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
RafaelGSS pushed a commit that referenced this pull request Aug 30, 2024
This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.

PR-URL: #54501
Fixes: #53639
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
RafaelGSS pushed a commit that referenced this pull request Aug 30, 2024
This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.

PR-URL: #54501
Fixes: #53639
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
RafaelGSS added a commit that referenced this pull request Aug 30, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Aug 30, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
@RafaelGSS RafaelGSS mentioned this pull request Aug 30, 2024
RafaelGSS added a commit that referenced this pull request Aug 31, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Aug 31, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Sep 1, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Sep 2, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Sep 3, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
RafaelGSS added a commit that referenced this pull request Sep 3, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) #54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) #54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) #54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) #54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) #53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) #53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) #54394

PR-URL: #54560
@targos targos added the dont-land-on-v20.x PRs that should not land on the v20.x-staging branch and should not be released in v20.x. label Sep 22, 2024
Copy link

@CharlesCowan CharlesCowan left a comment

Choose a reason for hiding this comment

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

🔥

louwers pushed a commit to louwers/node that referenced this pull request Nov 2, 2024
This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.

PR-URL: nodejs#54501
Fixes: nodejs#53639
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
louwers pushed a commit to louwers/node that referenced this pull request Nov 2, 2024
Notable changes:

net:
  * (SEMVER-MINOR) exclude ipv6 loopback addresses from server.listen (Giovanni Bucci) nodejs#54264
src:
  * (SEMVER-MINOR) add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE (Joyee Cheung) nodejs#54501
src,lib:
  * (SEMVER-MINOR) add performance.uvMetricsInfo (Rafael Gonzaga) nodejs#54413
test_runner:
  * (SEMVER-MINOR) add support for coverage thresholds (Aviv Keller) nodejs#54429
  * (SEMVER-MINOR) support running tests in process (Colin Ihrig) nodejs#53927
  * (SEMVER-MINOR) defer inheriting hooks until run() (Colin Ihrig) nodejs#53927
vm:
  * (SEMVER-MINOR) introduce vanilla contexts via vm.constants.DONT_CONTEXTIFY (Joyee Cheung) nodejs#54394

PR-URL: nodejs#54560
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. c++ Issues and PRs that require attention from people who are familiar with C++. commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. dont-land-on-v20.x PRs that should not land on the v20.x-staging branch and should not be released in v20.x. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. notable-change PRs with changes that should be highlighted in changelogs. semver-minor PRs that contain new features and should be released in the next minor version.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

APIs for libraries/frameworks/tools to control on-disk compilation cache (NODE_COMPILE_CACHE)