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.

Author: joyeecheung

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

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,

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;

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) {

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

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'));
+}

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;
+      }
+    });
+}