module: implement flushCompileCache()

doc/api/module.md

@@ -199,6 +199,13 @@ Compilation cache generated by one version of Node.js can not be reused by a dif
 version of Node.js. Cache generated by different versions of Node.js will be stored
 separately if the same base directory is used to persist the cache, so they can co-exist.
 
+At the moment, when the compile cache is enabled and a module is loaded afresh, the
+code cache is generated from the compiled code immediately, but will only be written
+to disk when the Node.js instance is about to exit. This is subject to change. The
+[`module.flushCompileCache()`][] method can be used to ensure the accumulated code cache
+is flushed to disk in case the application wants to spawn other Node.js instances
+and let them share the cache long before the parent exits.
+
 ### `module.getCompileCacheDir()`
 
 <!-- YAML
@@ -1101,6 +1108,21 @@ added:
 `path` is the resolved path for the file for which a corresponding source map
 should be fetched.
 
+### `module.flushCompileCache()`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+Flush the [module compile cache][] accumulated from modules already loaded
+in the current Node.js instance to disk. This returns after all the flushing
+file system operations come to an end, no matter they succeed or not. If there
+are any errors, this will fail silently, since compile cache misses should not
+interfer with the actual operation of the application.
+
 ### Class: `module.SourceMap`
 
 <!-- YAML
@@ -1216,6 +1238,7 @@ returned object contains the following keys:
 [`initialize`]: #initialize
 [`module.constants.compileCacheStatus`]: #moduleconstantscompilecachestatus
 [`module.enableCompileCache()`]: #moduleenablecompilecachecachedir
+[`module.flushCompileCache()`]: #moduleflushcompilecache
 [`module.getCompileCacheDir()`]: #modulegetcompilecachedir
 [`module`]: #the-module-object
 [`os.tmpdir()`]: os.md#ostmpdir

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

@@ -215,6 +215,8 @@ CompileCacheEntry* CompileCacheHandler::GetOrInsert(
  return loaded->second.get();
  }
 
+ // If the code hash mismatches, the code has changed, discard the stale entry
+ // and create a new one.
  auto emplaced =
  compiler_cache_store_.emplace(key, std::make_unique<CompileCacheEntry>());
  auto* result = emplaced.first->second.get();
@@ -283,23 +285,33 @@ void CompileCacheHandler::MaybeSave(CompileCacheEntry* entry,
  MaybeSaveImpl(entry, func, rejected);
 }
 
-// Layout of a cache file:
-// [uint32_t] magic number
-// [uint32_t] code size
-// [uint32_t] code hash
-// [uint32_t] cache size
-// [uint32_t] cache hash
-// .... compile cache content ....
+/**
+ * Persist the compile cache accumulated in memory to disk.
+ *
+ * To avoid race conditions, the cache file includes hashes of the original
+ * source code and the cache content. It's first written to a temporary file
+ * before being renamed to the target name.
+ *
+ * Layout of a cache file:
+ * [uint32_t] magic number
+ * [uint32_t] code size
+ * [uint32_t] code hash
+ * [uint32_t] cache size
+ * [uint32_t] cache hash
+ * .... compile cache content ....
+ */
 void CompileCacheHandler::Persist(){
  DCHECK(!compile_cache_dir_.empty());
 
- // NOTE(joyeecheung): in most circumstances the code caching reading
- // writing logic is lenient enough that it's fine even if someone
- // overwrites the cache (that leads to either size or hash mismatch
- // in subsequent loads and the overwritten cache will be ignored).
- // Also in most use cases users should not change the files on disk
- // too rapidly. Therefore locking is not currently implemented to
- // avoid the cost.
+ // 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){
@@ -312,6 +324,11 @@ void CompileCacheHandler::Persist(){
  entry->source_filename);
  continue;
  }
+ if (entry->persisted == true){
+ Debug("[compile cache] skip %s because cache was already persisted\n",
+ entry->source_filename);
+ continue;
+ }
 
  DCHECK_EQ(entry->cache->buffer_policy,
  v8::ScriptCompiler::CachedData::BufferOwned);
@@ -328,27 +345,94 @@ void CompileCacheHandler::Persist(){
  headers[kCodeHashOffset] = entry->code_hash;
  headers[kCacheHashOffset] = cache_hash;
 
- Debug("[compile cache] writing cache for %s in %s [%d %d %d %d %d]...",
+ // Generate the temporary filename.
+ // The temporary file should be placed in a location like:
+ //
+ // $NODE_COMPILE_CACHE_DIR/v23.0.0-pre-arm64-5fad6d45-501/e7f8ef7f.cache.tcqrsK
+ //
+ // 1. $NODE_COMPILE_CACHE_DIR either comes from the $NODE_COMPILE_CACHE
+ // environment
+ // variable or `module.enableCompileCache()`.
+ // 2. v23.0.0-pre-arm64-5fad6d45-501 is the sub cache directory and
+ // e7f8ef7f is the hash for the cache (see
+ // CompileCacheHandler::Enable()),
+ // 3. tcqrsK is generated by uv_fs_mkstemp() as a temporary indentifier.
+ uv_fs_t mkstemp_req;
+ auto cleanup_mkstemp =
+ OnScopeLeave([&mkstemp_req](){uv_fs_req_cleanup(&mkstemp_req)});
+ std::string cache_filename_tmp = entry->cache_filename + ".XXXXXX"
+ Debug("[compile cache] Creating temporary file for cache of %s...",
+ entry->source_filename);
+ int err = uv_fs_mkstemp(
+ nullptr, &mkstemp_req, cache_filename_tmp.c_str(), nullptr);
+ if (err < 0){
+ Debug("failed. %s\n", uv_strerror(err));
+ continue;
+ }
+ Debug(" -> %s\n", mkstemp_req.path);
+ Debug("[compile cache] writing cache for %s to temporary file %s [%d %d %d "
+ "%d %d]...",
  entry->source_filename,
-entry->cache_filename,
+mkstemp_req.path,
  headers[kMagicNumberOffset],
  headers[kCodeSizeOffset],
  headers[kCacheSizeOffset],
  headers[kCodeHashOffset],
  headers[kCacheHashOffset]);
 
+ // Write to the temporary file.
  uv_buf_t headers_buf = uv_buf_init(reinterpret_cast<char*>(headers.data()),
  headers.size() * sizeof(uint32_t));
  uv_buf_t data_buf = uv_buf_init(cache_ptr, entry->cache->length);
  uv_buf_t bufs[] ={headers_buf, data_buf};
 
- int err = WriteFileSync(entry->cache_filename.c_str(), bufs, 2);
+ uv_fs_t write_req;
+ auto cleanup_write =
+ OnScopeLeave([&write_req](){uv_fs_req_cleanup(&write_req)});
+ err = uv_fs_write(
+ nullptr, &write_req, mkstemp_req.result, bufs, 2, 0, nullptr);
+ if (err < 0){
+ Debug("failed: %s\n", uv_strerror(err));
+ continue;
+ }
+
+ uv_fs_t close_req;
+ auto cleanup_close =
+ OnScopeLeave([&close_req](){uv_fs_req_cleanup(&close_req)});
+ err = uv_fs_close(nullptr, &close_req, mkstemp_req.result, nullptr);
+
+ if (err < 0){
+ Debug("failed: %s\n", uv_strerror(err));
+ continue;
+ }
+
+ Debug("success\n");
+
+ // Rename the temporary file to the actual cache file.
+ uv_fs_t rename_req;
+ auto cleanup_rename =
+ OnScopeLeave([&rename_req](){uv_fs_req_cleanup(&rename_req)});
+ std::string cache_filename_final = entry->cache_filename;
+ Debug("[compile cache] Renaming %s to %s...",
+ mkstemp_req.path,
+ cache_filename_final);
+ err = uv_fs_rename(nullptr,
+ &rename_req,
+ mkstemp_req.path,
+ cache_filename_final.c_str(),
+ nullptr);
  if (err < 0){
  Debug("failed: %s\n", uv_strerror(err));
- } else{
- Debug("success\n");
+ continue;
  }
+ Debug("success\n");
+ entry->persisted = true;
  }
+
+ // Clear the map at the end in one go instead of during the iteration to
+ // avoid rehashing costs.
+ Debug("[compile cache] Clear deserialized cache.\n");
+ compiler_cache_store_.clear();
 }
 
 CompileCacheHandler::CompileCacheHandler(Environment* env)

src/compile_cache.h

@@ -30,6 +30,8 @@ struct CompileCacheEntry{
  std::string source_filename;
  CachedCodeType type;
 bool refreshed = false;
+bool persisted = false;
+
 // Copy the cache into a new store for V8 to consume. Caller takes
 // ownership.
  v8::ScriptCompiler::CachedData* CopyCache() const;

src/env.cc

@@ -847,14 +847,12 @@ Environment::Environment(IsolateData* isolate_data,
  }
  }
 
- // We are supposed to call builtin_loader_.SetEagerCompile() in
- // snapshot mode here because it's beneficial to compile built-ins
- // loaded in the snapshot eagerly and include the code of inner functions
- // that are likely to be used by user since they are part of the core
- // startup. But this requires us to start the coverage collections
- // before Environment/Context creation which is not currently possible.
- // TODO(joyeecheung): refactor V8ProfilerConnection classes to parse
- // JSON without v8 and lift this restriction.
+ // Compile builtins eagerly when building the snapshot so that inner functions
+ // of essential builtins that are loaded in the snapshot can have faster first
+ // invocation.
+ if (isolate_data->is_building_snapshot()){
+ builtin_loader()->SetEagerCompile();
+ }
 
  // We'll be creating new objects so make sure we've entered the context.
  HandleScope handle_scope(isolate);
@@ -1143,7 +1141,7 @@ CompileCacheEnableResult Environment::EnableCompileCache(
  compile_cache_handler_ = std::move(handler);
  AtExit(
  [](void* env){
- static_cast<Environment*>(env)->compile_cache_handler()->Persist();
+ static_cast<Environment*>(env)->FlushCompileCache();
  },
  this);
  }
@@ -1160,6 +1158,13 @@ CompileCacheEnableResult Environment::EnableCompileCache(
  return result;
 }
 
+void Environment::FlushCompileCache(){
+ if (!compile_cache_handler_ || compile_cache_handler_->cache_dir().empty()){
+ return;
+ }
+ compile_cache_handler_->Persist();
+}
+
 void Environment::ExitEnv(StopFlags::Flags flags){
  // Should not access non-thread-safe methods here.
  set_stopping(true);

src/env.h

@@ -1041,6 +1041,7 @@ class Environment final : public MemoryRetainer{
  // Enable built-in compile cache if it has not yet been enabled.
  // The cache will be persisted to disk on exit.
  CompileCacheEnableResult EnableCompileCache(const std::string& cache_dir);
+ void FlushCompileCache();
 
  void RunAndClearNativeImmediates(bool only_refed = false);
  void RunAndClearInterrupts();

src/node_modules.cc

@@ -435,11 +435,33 @@ 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();
+ Debug(env,
+ DebugCategory::COMPILE_CACHE,
+ "[compile cache] module.flushCompileCache() finished.\n");
+}
+
 void EnableCompileCache(const FunctionCallbackInfo<Value>& args){
- CHECK(args[0]->IsString());
  Isolate* isolate = args.GetIsolate();
  Local<Context> context = isolate->GetCurrentContext();
  Environment* env = Environment::GetCurrent(context);
+ if (!args[0]->IsString()){
+ THROW_ERR_INVALID_ARG_TYPE(env, "cacheDir should be a string");
+ return;
+ }
  Utf8Value value(isolate, args[0]);
  CompileCacheEnableResult result = env->EnableCompileCache(*value);
  std::vector<Local<Value>> values ={
@@ -477,6 +499,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,
@@ -509,6 +532,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-error.js

@@ -0,0 +1,11 @@
+'use strict'
+
+// This tests module.enableCompileCache() throws when an invalid argument is passed.
+
+require('../common');
+const{enableCompileCache } = require('module');
+const assert = require('assert');
+
+for (const invalid of [0, null, false, () =>{},{}, []]){
+ assert.throws(() => enableCompileCache(invalid),{code: 'ERR_INVALID_ARG_TYPE'});
+}