perf(reference): overlap reference-source identity lookups in traversal order (#11585)

The reference-source reader made about nine serial filesystem calls per
directory. It now runs its read-only identity lookups ahead of their turn,
bounded to four running at once (libuv's default filesystem concurrency):
opening admissions of the next pending directories, metadata of the next
listed names, and closing admissions of directories already enumerated.
Results are applied in traversal order: policy and exclusion callbacks keep
their order, the first error in traversal order is returned, a failure a
started lookup observed is retained, and every started lookup settles before
the read returns. Running opening admissions are counted, so older siblings
buried by deeper levels cannot raise concurrency with tree depth.

Measured on macOS, Node 24.22.1: the 130,000-directory regression's
reference-source read 27.5 s -> 17.2 s; a 20,000-directory flat tree
2.1-2.3 s -> 1.2 s; an 8,641-file source tree 1.41 s -> 1.31 s.

Refs #11365
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 07:57:51 +08:00
1 parent e3eb4c1749
commit 65f78edce5
5 files changed
+356 -82

No files matched your search

+32 -8
View File
@@ -4,7 +4,11 @@ import {
ArtifactReaderFailure,
type ArtifactResourceScope,
} from "../resources/index.js";
import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
import {
prefetchDirectoryValidations,
settleDirectoryAdmissions,
traverseDirectory,
} from "./ReferenceSourceReaderEntries.js";
import type {
ReferenceSourceReaderOptions,
ReferenceSourceRead,
@@ -76,6 +80,8 @@ const readSource = async (
entries: [],
exclusions: [],
pending: [{ path: canonicalRoot }],
settling: [],
openingLookups: 0,
bytesRead: 0,
};
const traversal = await traverse(state);
@@ -117,12 +123,30 @@ const readSource = async (
const traverse = async (
state: TraversalState,
): Promise<ReferenceSourceResult<undefined>> => {
while (state.pending.length > 0) {
if (isAborted(state.signal)) return err(cancelled(state.signal));
const current = state.pending.pop();
if (current === undefined) break;
const result = await traverseDirectory(state, current);
if (!result.ok) return result;
try {
while (state.pending.length > 0) {
if (isAborted(state.signal)) {
await settleDirectoryAdmissions(state);
return err(cancelled(state.signal));
}
prefetchDirectoryValidations(state);
const current = state.pending.pop();
if (current === undefined) break;
const result = await traverseDirectory(state, current);
if (!result.ok) {
await settleDirectoryAdmissions(state);
return result;
}
}
await settleDirectoryAdmissions(state);
return isAborted(state.signal)
? err(cancelled(state.signal))
: ok(undefined);
} finally {
// No observation started ahead of its turn outlives the read.
await Promise.allSettled([
...state.settling,
...state.pending.flatMap(({ validation }) => validation ?? []),
]);
}
return ok(undefined);
};