Unverified Commit 3beb4665 authored by Luke Sandberg's avatar Luke Sandberg Committed by GitHub

Batch require cache deletion to avoid quadratic scanning (#90625)

### What?

Rewrites `deleteFromRequireCache()` in `packages/next/src/server/dev/require-cache.ts` to accept an array of file paths and perform a single scan of `require.cache`, instead of one full scan per file. Adds a `deleteCacheBatch()` export and updates all three batch call sites to use it.

### Why?

During server-side HMR, `deleteCache()` is called in loops — once per server path in the turbopack hot-reloader (5-20 files), up to 15 times per `writeManifests()` in the manifest-loader, and 2 + N times (runtime chunks + page entries) in the webpack plugin's `afterEmit` hook. Each call scans the **entire** `require.cache` to clean up parent-child references, making the overall cost O(N × C) where C is the cache size. In large apps with thousands of cached modules, this becomes a meaningful bottleneck on every HMR update.

### How?

**Core change (`require-cache.ts`):** `deleteFromRequireCache` now accepts `string[]`. It resolves all paths upfront, collects target modules into a `Set<NodeModule>`, then does one scan of `require.cache` using `Set.has()` (O(1) lookup) to filter children arrays. For single-item callers (`deleteCache`), the overhead of a 1-element Set is negligible.

**Call site updates:**
- **`hot-reloader-turbopack.ts`**: Collects files to delete into an array during the `serverPaths` loop, calls `deleteCacheBatch()` once after. `clearModuleContext` stays per-file (separate system).
- **`manifest-loader.ts`**: Adds `pendingCacheDeletes` array to `TurbopackManifestLoader`. All ~15 `deleteCache()` calls in `write*` methods become `push()` calls. Flushed at the end of `writeManifests()` with a single `deleteCacheBatch()`. Moving cache deletion to after all `writeFileAtomic` calls is safe (synchronous code, no interleaving) and slightly better (new files on disk before cache is cleared).
- **`nextjs-require-cache-hot-reloader.ts`** (webpack): Batches the `afterEmit` hook — collects runtime chunk + page entry paths, calls `deleteCacheBatch()` once. The `assetEmitted` tap callback stays as individual `deleteCache()`.

**Theoretical improvement:**

| Call Site | Before (cache scans) | After | Improvement |
|-----------|---------------------|-------|-------------|
| turbopack `clearRequireCache` | N (5-20) | 1 | 5-20× fewer scans |
| manifest-loader `writeManifests` | up to 15 | 1 | up to 15× fewer scans |
| webpack `afterEmit` | 2 + page count | 1 | up to 50× fewer scans |

### Benchmark

Tested with a generated 250-route app with 50 API route handlers importing server external packages (zod, lodash, express, pg, ioredis) plus middleware. API route handlers are key because unlike bundled app-router pages, they create real `require.cache` depth with native Node.js module loading.

**Results (steady-state, 18 paths / 7 found / 781 nodes / ~1800 edges):**

| Mode | Time per batch |
|------|---------------|
| **Batched** (1 scan) | **~0.24ms** |
| **Unbatched** (18 individual scans) | **~0.70ms** |
| **Speedup** | **~3×** |

Raw data (representative samples):

```
# Batched (1 scan of require.cache)
[PERF] deleteCacheBatch(batch=true): 18 paths (7 found), 781 nodes, 1772 edges, 0.283ms
[PERF] deleteCacheBatch(batch=true): 18 paths (7 found), 781 nodes, 1800 edges, 0.250ms
[PERF] deleteCacheBatch(batch=true): 18 paths (7 found), 781 nodes, 1912 edges, 0.283ms

# Unbatched (18 individual scans)
[PERF] deleteCacheBatch(batch=false): 18 paths (7 found), 781 nodes, 1772 edges, 0.671ms
[PERF] deleteCacheBatch(batch=false): 18 paths (7 found), 781 nodes, 1800 edges, 0.649ms
[PERF] deleteCacheBatch(batch=false): 18 paths (7 found), 781 nodes, 1912 edges, 0.716ms
```

The speedup scales with cache complexity — in production apps with more server externals (ORMs, validation libs, etc.) the cache would be larger and the improvement proportionally greater. With only bundled app-router pages (few edges in require.cache graph), the difference is negligible since most of the graph complexity comes from native Node.js module loading.
parent dc57cde3
......@@ -22,33 +22,24 @@ export class NextJsRequireCacheHotReloader implements WebpackPluginInstance {
compiler.hooks.assetEmitted.tap(PLUGIN_NAME, (_file, { targetPath }) => {
// Clear module context in this process
clearModuleContext(targetPath)
deleteCache(targetPath)
deleteCache([targetPath])
})
compiler.hooks.afterEmit.tapPromise(PLUGIN_NAME, async (compilation) => {
for (const name of RUNTIME_NAMES) {
const runtimeChunkPath = path.join(
compilation.outputOptions.path!,
`${name}.js`
)
deleteCache(runtimeChunkPath)
}
// we need to make sure to clear all server entries from cache
// since they can have a stale webpack-runtime cache
// which needs to always be in-sync
const entries = [...compilation.entrypoints.keys()].filter((entry) => {
const isAppPath = entry.toString().startsWith('app/')
return entry.toString().startsWith('pages/') || isAppPath
})
for (const page of entries) {
const outputPath = path.join(
compilation.outputOptions.path!,
page + '.js'
)
deleteCache(outputPath)
const outputPath = compilation.outputOptions.path!
const allPaths = RUNTIME_NAMES.map((name) =>
path.join(outputPath, `${name}.js`)
)
for (const entry of compilation.entrypoints.keys()) {
if (entry.startsWith('pages/') || entry.startsWith('app/')) {
allPaths.push(path.join(outputPath, `${entry}.js`))
}
}
deleteCache(allPaths)
})
}
}
......@@ -619,6 +619,7 @@ export async function createHotReloaderTurbopack(
isAppPage &&
writtenEndpoint.type !== 'edge'
const filesToDelete: string[] = []
for (const file of serverPaths) {
clearModuleContext(file)
......@@ -631,9 +632,10 @@ export async function createHotReloaderTurbopack(
!usesServerHmr ||
!serverHmrSubscriptions?.has(relativePath)
) {
deleteCache(file)
filesToDelete.push(file)
}
}
deleteCache(filesToDelete)
// Reset the fetch patch so patchFetch() can re-wrap on the next request.
if (serverPaths.length > 0) {
......@@ -1841,9 +1843,10 @@ export async function createHotReloaderTurbopack(
serverHmrSubscriptions = setupServerHmr(project, {
clear: async () => {
// Clear Node's require cache of all Turbopack-built modules
for (const chunkPath of serverHmrSubscriptions?.keys() ?? []) {
deleteCache(join(distDir, chunkPath))
}
const chunkPaths = [...(serverHmrSubscriptions?.keys() ?? [])].map(
(chunkPath) => join(distDir, chunkPath)
)
deleteCache(chunkPaths)
// Clear Turbopack's runtime caches
if (typeof __next__clear_chunk_cache__ === 'function') {
......
......@@ -2,34 +2,67 @@ import isError from '../../lib/is-error'
import { realpathSync } from '../../lib/realpath'
import { clearManifestCache } from '../load-manifest.external'
function deleteFromRequireCache(filePath: string) {
try {
filePath = realpathSync(filePath)
} catch (e) {
if (isError(e) && e.code !== 'ENOENT') throw e
/**
* Batch delete modules from require.cache with a single scan.
*
* When deleting N modules, this performs ONE scan of require.cache
* instead of N scans, reducing complexity from O(N * C) to O(C + N)
* where C = size of require.cache.
*/
function deleteFromRequireCache(filePaths: string[]): void {
// Phase 1: Resolve all paths and collect modules to delete
const resolvedPaths: string[] = []
const modsToDelete = new Set<NodeModule>()
for (let filePath of filePaths) {
try {
filePath = realpathSync(filePath)
} catch (e) {
if (isError(e) && e.code !== 'ENOENT') throw e
}
const mod = require.cache[filePath]
if (mod) {
resolvedPaths.push(filePath)
modsToDelete.add(mod)
}
}
const mod = require.cache[filePath]
if (mod) {
// remove the child reference from all parent modules
for (const parent of Object.values(require.cache)) {
if (parent?.children) {
const idx = parent.children.indexOf(mod)
if (idx >= 0) parent.children.splice(idx, 1)
if (modsToDelete.size === 0) return
// Phase 2: Single scan of require.cache to remove child references
const modules = Object.values(require.cache)
for (let m = 0; m < modules.length; m++) {
const children = modules[m]?.children
if (children && children.length) {
let len = children.length
for (let i = 0; i < len; i++) {
if (modsToDelete.has(children[i])) {
children[i] = children[--len]
i-- // re-check swapped element
}
}
children.length = len
}
// remove parent references from external modules
for (const child of mod.children) {
child.parent = null
}
// Phase 3: Clear parent references from children and delete cache entries
for (const mod of modsToDelete) {
const children = mod.children
for (let i = 0; i < children.length; i++) {
if (children[i].parent === mod) {
children[i].parent = null
}
}
}
for (const filePath of resolvedPaths) {
delete require.cache[filePath]
return true
}
return false
}
export function deleteCache(filePath: string) {
// try to clear it from the fs cache
clearManifestCache(filePath)
deleteFromRequireCache(filePath)
export function deleteCache(filePaths: string[]) {
for (const filePath of filePaths) {
clearManifestCache(filePath)
}
deleteFromRequireCache(filePaths)
}
......@@ -208,6 +208,7 @@ export class TurbopackManifestLoader {
/// interceptionRewrites that have been written to disk
/// This is used to avoid unnecessary writes if the rewrites haven't changed
private cachedInterceptionRewrites: string | undefined = undefined
private pendingCacheDeletes: string[] = []
private readonly distDir: string
private readonly buildId: string
......@@ -317,8 +318,8 @@ export class TurbopackManifestLoader {
`${SERVER_REFERENCE_MANIFEST}.js`
)
const json = JSON.stringify(actionManifest, null, 2)
deleteCache(actionManifestJsonPath)
deleteCache(actionManifestJsPath)
this.pendingCacheDeletes.push(actionManifestJsonPath)
this.pendingCacheDeletes.push(actionManifestJsPath)
writeFileAtomic(actionManifestJsonPath, json)
writeFileAtomic(
actionManifestJsPath,
......@@ -350,7 +351,7 @@ export class TurbopackManifestLoader {
'server',
APP_PATHS_MANIFEST
)
deleteCache(appPathsManifestPath)
this.pendingCacheDeletes.push(appPathsManifestPath)
writeFileAtomic(
appPathsManifestPath,
JSON.stringify(appPathsManifest, null, 2)
......@@ -363,7 +364,7 @@ export class TurbopackManifestLoader {
}
const webpackStats = this.mergeWebpackStats(this.webpackStats.values())
const path = join(this.distDir, 'server', WEBPACK_STATS)
deleteCache(path)
this.pendingCacheDeletes.push(path)
writeFileAtomic(path, JSON.stringify(webpackStats, null, 2))
}
......@@ -382,8 +383,8 @@ export class TurbopackManifestLoader {
'server',
`${SUBRESOURCE_INTEGRITY_MANIFEST}.js`
)
deleteCache(pathJson)
deleteCache(pathJs)
this.pendingCacheDeletes.push(pathJson)
this.pendingCacheDeletes.push(pathJs)
writeFileAtomic(pathJson, JSON.stringify(sriManifest, null, 2))
writeFileAtomic(
pathJs,
......@@ -563,7 +564,7 @@ export class TurbopackManifestLoader {
'server',
`${INTERCEPTION_ROUTE_REWRITE_MANIFEST}.js`
)
deleteCache(interceptionRewriteManifestPath)
this.pendingCacheDeletes.push(interceptionRewriteManifestPath)
writeFileAtomic(
interceptionRewriteManifestPath,
......@@ -589,8 +590,8 @@ export class TurbopackManifestLoader {
`${MIDDLEWARE_BUILD_MANIFEST}.js`
)
deleteCache(buildManifestPath)
deleteCache(middlewareBuildManifestPath)
this.pendingCacheDeletes.push(buildManifestPath)
this.pendingCacheDeletes.push(middlewareBuildManifestPath)
writeFileAtomic(buildManifestPath, JSON.stringify(buildManifest, null, 2))
writeFileAtomic(
middlewareBuildManifestPath,
......@@ -609,7 +610,7 @@ export class TurbopackManifestLoader {
this.distDir,
`fallback-${BUILD_MANIFEST}`
)
deleteCache(fallbackBuildManifestPath)
this.pendingCacheDeletes.push(fallbackBuildManifestPath)
writeFileAtomic(
fallbackBuildManifestPath,
JSON.stringify(fallbackBuildManifest, null, 2)
......@@ -730,8 +731,8 @@ export class TurbopackManifestLoader {
'server',
`${NEXT_FONT_MANIFEST}.js`
)
deleteCache(fontManifestJsonPath)
deleteCache(fontManifestJsPath)
this.pendingCacheDeletes.push(fontManifestJsonPath)
this.pendingCacheDeletes.push(fontManifestJsPath)
writeFileAtomic(fontManifestJsonPath, json)
writeFileAtomic(
fontManifestJsPath,
......@@ -875,7 +876,7 @@ export class TurbopackManifestLoader {
'server',
MIDDLEWARE_MANIFEST
)
deleteCache(middlewareManifestPath)
this.pendingCacheDeletes.push(middlewareManifestPath)
writeFileAtomic(
middlewareManifestPath,
JSON.stringify(middlewareManifest, null, 2)
......@@ -891,7 +892,7 @@ export class TurbopackManifestLoader {
2
)};self.__MIDDLEWARE_MATCHERS_CB && self.__MIDDLEWARE_MATCHERS_CB()`
deleteCache(clientMiddlewareManifestPath)
this.pendingCacheDeletes.push(clientMiddlewareManifestPath)
writeFileAtomic(
join(this.distDir, clientMiddlewareManifestPath),
clientMiddlewareManifestJs
......@@ -931,7 +932,7 @@ export class TurbopackManifestLoader {
}
const pagesManifest = this.mergePagesManifests(this.pagesManifests.values())
const pagesManifestPath = join(this.distDir, 'server', PAGES_MANIFEST)
deleteCache(pagesManifestPath)
this.pendingCacheDeletes.push(pagesManifestPath)
writeFileAtomic(pagesManifestPath, JSON.stringify(pagesManifest, null, 2))
}
......@@ -962,6 +963,12 @@ export class TurbopackManifestLoader {
if (process.env.TURBOPACK_STATS != null) {
this.writeWebpackStats()
}
// Flush all queued cache deletions in a single require.cache scan
if (this.pendingCacheDeletes.length > 0) {
deleteCache(this.pendingCacheDeletes)
this.pendingCacheDeletes = []
}
}
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment