From f54cb3baa5b8b72c07b53a1d5b6447c3f11366a8 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Wed, 4 Sep 2024 20:18:12 +0200
Subject: [PATCH] module: implement flushCompileCache()

This implements an API for users to intentionally flush the
accumulated compile cache instead of waiting until process
shutdown. It may be useful for application that loads dependencies
first and then either reload itself in other instances, or spawning
other instances that load an overlapping set of its dependencies -
in this case its useful to flush the cache early instead of waiting
until the shutdown of itself.

Currently flushing is triggered by either process
shutdown or user requests. In the future we should simply start the
writes right after module loading on a separate thread, and this method
only blocks until all the pending writes (if any) on the other thread
are finished. In that case, the off-thread writes should finish long
before any attempt of flushing is made so the method would then only
incur a negligible overhead from thread synchronization.
---
 doc/api/module.md                             | 22 +++++++++
 lib/internal/modules/helpers.js               |  2 +
 lib/module.js                                 |  3 ++
 src/compile_cache.cc                          |  7 +++
 src/node_modules.cc                           | 16 +++++++
 test/fixtures/compile-cache-flush.js          | 21 +++++++++
 test/parallel/test-compile-cache-api-flush.js | 47 +++++++++++++++++++
 7 files changed, 118 insertions(+)
 create mode 100644 test/fixtures/compile-cache-flush.js
 create mode 100644 test/parallel/test-compile-cache-api-flush.js

diff --git a/doc/api/module.md b/doc/api/module.md
index 3bb25c3f313da1..7e4e1116789311 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -1101,6 +1101,28 @@ added:
 `path` is the resolved path for the file for which a corresponding source map
 should be fetched.
 
+### `module.flushCompileCache([keepDeserializedCache])`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+* `keepDeserializedCache` {boolean} Whether the cache read from disk and already deserialized to
+                                    compile the corresponding modules should be kept after flushing.
+                                    Defaults to `false`.
+
+Flush the [module compile cache][] accumulated from loaded modules to disk.
+
+In most cases, it's not necessary to set the `keepDeserializedCache` option. After a module
+is compiled, there is another tier of module cache in Node.js, so keeping the code cache that
+is already deserialized into a live module usually just increases memory usage for no
+additional benefit. It's only useful if users intentionally purge the live cache e.g.
+by deleting from `require.cache` while expecting most source code to still remain unchanged
+and can be recompiled using the cache already read from disk.
+
 ### Class: `module.SourceMap`
 
 <!-- YAML
diff --git a/lib/internal/modules/helpers.js b/lib/internal/modules/helpers.js
index a31c2a74d88b36..e5cd20ed0369c4 100644
--- a/lib/internal/modules/helpers.js
+++ b/lib/internal/modules/helpers.js
@@ -40,6 +40,7 @@ const {
   enableCompileCache: _enableCompileCache,
   getCompileCacheDir: _getCompileCacheDir,
   compileCacheStatus: _compileCacheStatus,
+  flushCompileCache,
 } = internalBinding('modules');
 
 let debug = require('internal/util/debuglog').debuglog('module', (fn) => {
@@ -485,6 +486,7 @@ module.exports = {
   assertBufferSource,
   constants,
   enableCompileCache,
+  flushCompileCache,
   getBuiltinModule,
   getCjsConditions,
   getCompileCacheDir,
diff --git a/lib/module.js b/lib/module.js
index fe0eb937eaeac0..48ba9215b081eb 100644
--- a/lib/module.js
+++ b/lib/module.js
@@ -7,6 +7,7 @@ const { SourceMap } = require('internal/source_map/source_map');
 const {
   constants,
   enableCompileCache,
+  flushCompileCache,
   getCompileCacheDir,
 } = require('internal/modules/helpers');
 
@@ -15,5 +16,7 @@ Module.register = register;
 Module.SourceMap = SourceMap;
 Module.constants = constants;
 Module.enableCompileCache = enableCompileCache;
+Module.flushCompileCache = flushCompileCache;
+
 Module.getCompileCacheDir = getCompileCacheDir;
 module.exports = Module;
diff --git a/src/compile_cache.cc b/src/compile_cache.cc
index a284960bd5d443..044023bf24b4a5 100644
--- a/src/compile_cache.cc
+++ b/src/compile_cache.cc
@@ -305,6 +305,13 @@ void CompileCacheHandler::Persist(bool keep_deserialized_cache) {
 
   // TODO(joyeecheung): do this using a separate event loop to utilize the
   // libuv thread pool and do the file system operations concurrently.
+  // TODO(joyeecheung): Currently flushing is triggered by either process
+  // shutdown or user requests. In the future we should simply start the
+  // writes right after module loading on a separate thread, and this method
+  // only blocks until all the pending writes (if any) on the other thread are
+  // finished. In that case, the off-thread writes should finish long
+  // before any attempt of flushing is made so the method would then only
+  // incur a negligible overhead from thread synchronization.
   for (auto& pair : compiler_cache_store_) {
     auto* entry = pair.second.get();
     if (entry->cache == nullptr) {
diff --git a/src/node_modules.cc b/src/node_modules.cc
index 721b5e1e4b457d..867ef5027eaa86 100644
--- a/src/node_modules.cc
+++ b/src/node_modules.cc
@@ -435,6 +435,20 @@ void BindingData::GetPackageScopeConfig(
           .ToLocalChecked());
 }
 
+void FlushCompileCache(const FunctionCallbackInfo<Value>& args) {
+  Isolate* isolate = args.GetIsolate();
+  Local<Context> context = isolate->GetCurrentContext();
+  Environment* env = Environment::GetCurrent(context);
+
+  if (!args[0]->IsBoolean() && !args[0]->IsUndefined()) {
+    THROW_ERR_INVALID_ARG_TYPE(env, "keepDeserializedCache should be a boolean");
+    return;
+  }
+  Debug(env, DebugCategory::COMPILE_CACHE, "[compile cache] module.flushCompileCache() requested.\n");
+  env->FlushCompileCache(args[0]->IsTrue());
+  Debug(env, DebugCategory::COMPILE_CACHE, "[compile cache] module.flushCompileCache() finished.\n");
+}
+
 void EnableCompileCache(const FunctionCallbackInfo<Value>& args) {
   Isolate* isolate = args.GetIsolate();
   Local<Context> context = isolate->GetCurrentContext();
@@ -480,6 +494,7 @@ void BindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
   SetMethod(isolate, target, "getPackageScopeConfig", GetPackageScopeConfig);
   SetMethod(isolate, target, "enableCompileCache", EnableCompileCache);
   SetMethod(isolate, target, "getCompileCacheDir", GetCompileCacheDir);
+  SetMethod(isolate, target, "flushCompileCache", FlushCompileCache);
 }
 
 void BindingData::CreatePerContextProperties(Local<Object> target,
@@ -512,6 +527,7 @@ void BindingData::RegisterExternalReferences(
   registry->Register(GetPackageScopeConfig);
   registry->Register(EnableCompileCache);
   registry->Register(GetCompileCacheDir);
+  registry->Register(FlushCompileCache);
 }
 
 }  // namespace modules
diff --git a/test/fixtures/compile-cache-flush.js b/test/fixtures/compile-cache-flush.js
new file mode 100644
index 00000000000000..8054f67b0ddaea
--- /dev/null
+++ b/test/fixtures/compile-cache-flush.js
@@ -0,0 +1,21 @@
+'use strict';
+
+const { flushCompileCache, getCompileCacheDir } = require('module');
+const { spawnSync } = require('child_process');
+const assert = require('assert');
+
+if (process.argv[2] !== 'child') {
+  // The test should be run with the compile cache already enabled and NODE_DEBUG_NATIVE=COMPILE_CACHE.
+  assert(getCompileCacheDir());
+  assert(process.env.NODE_DEBUG_NATIVE.includes('COMPILE_CACHE'));
+
+  flushCompileCache();
+
+  const child1 = spawnSync(process.execPath, [__filename, 'child']);
+  console.log(child1.stderr.toString().trim().split('\n').map(line => `[child1]${line}`).join('\n'));
+
+  flushCompileCache();
+
+  const child2 = spawnSync(process.execPath, [__filename, 'child']);
+  console.log(child2.stderr.toString().trim().split('\n').map(line => `[child2]${line}`).join('\n'));
+}
diff --git a/test/parallel/test-compile-cache-api-flush.js b/test/parallel/test-compile-cache-api-flush.js
new file mode 100644
index 00000000000000..7e66b1fee103db
--- /dev/null
+++ b/test/parallel/test-compile-cache-api-flush.js
@@ -0,0 +1,47 @@
+'use strict';
+
+// This tests module.flushCompileCache() works as expected.
+
+require('../common');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const assert = require('assert');
+const tmpdir = require('../common/tmpdir');
+const fixtures = require('../common/fixtures');
+
+{
+  // Test that it works with non-existent directory.
+  tmpdir.refresh();
+  const cacheDir = tmpdir.resolve('compile_cache');
+  spawnSyncAndAssert(
+    process.execPath,
+    [fixtures.path('compile-cache-flush.js')],
+    {
+      env: {
+        ...process.env,
+        NODE_DEBUG_NATIVE: 'COMPILE_CACHE',
+        NODE_COMPILE_CACHE: cacheDir,
+      },
+      cwd: tmpdir.path
+    },
+    {
+      stdout(output) {
+        // This contains output from the nested spawnings of compile-cache-flush.js.
+        assert.match(output, /child1.* cache for .*compile-cache-flush\.js was accepted, keeping the in-memory entry/);
+        assert.match(output, /child2.* cache for .*compile-cache-flush\.js was accepted, keeping the in-memory entry/);
+        return true;
+      },
+      stderr(output) {
+        // This contains output from the top-level spawning of compile-cache-flush.js.
+        assert.match(output, /reading cache from .*compile_cache.* for CommonJS .*compile-cache-flush\.js/);
+        assert.match(output, /compile-cache-flush\.js was not initialized, initializing the in-memory entry/);
+
+        const writeRE = /writing cache for .*compile-cache-flush\.js.*success/;
+        const flushRE = /module\.flushCompileCache\(\) finished/;
+        assert.match(output, writeRE);
+        assert.match(output, flushRE);
+        // The cache writing should happen before flushing finishes i.e. it's not delayed until process shutdown.
+        assert(output.match(writeRE).index < output.match(flushRE).index);
+        return true;
+      }
+    });
+}