Skip to content

[JSC] A load by name starts again when clearAll() overtook its fetch - #853

Draft
robobun wants to merge 1 commit into
mainfrom
robobun/cfa20256/module-load-by-name-reload-after-clear
Draft

robobun wants to merge 1 commit into
mainfrom
robobun/cfa20256/module-load-by-name-reload-after-clear

Conversation

@robobun

@robobun robobun commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Draft until the question in the notes (asked in #754) has an answer.

Problem

  • A bun --hot reload during an import() can leave the old file registered until the next save.
  • An import() has no registry entry until its fetch settles, so clearAll() removes nothing of it. moduleLoadTopSettled then registers the fetched source by key (JSMicrotask.cpp:1187). A failed fetch leaves its error on the module the key then holds.

Fix

  • clearAll() advances a registry epoch. An import() keeps the epoch it started under.
  • When its fetch settles under another epoch, moduleLoadTopSettled drops the result and calls loadModule() by name again. The import() settles with that load, which is made after the clear.
  • Verified: JSTests/stress/module-load-by-name-in-flight-when-registry-cleared.js (exit 3 on main's runtime, 0 here and with [JSC] A failed loadModule() stores its error in the registry entry it loaded #754 applied).
  • Self-reviewed: 38 concerns raised, 26 addressed. The other 12 are about Bun's half and wait for the answer.

Background

Downsides

  • A load by name pays 8 more instructions when nothing was cleared (release builds, disassembly) and 0 allocations. A static import pays 0.
  • The overtaken import() fetches twice. If the second fetch fails, it rejects where main resolved with the old module.
Notes

Question (also asked in #754)

Both candidate fixes stop the stale registration. They differ in what the overtaken import() settles with. Rows from a Bun build (bun --hot, a plugin onLoad holds the fetch of a.mjs across the reload, the module text carries the number of its fetch):

Row main keep its module start again (this PR)
the fetch ends with a module in flight: fetch 1, next: fetch 1 in flight: fetch 1, next: fetch 2, 2 evaluations in flight: fetch 2, next: fetch 2, 1 evaluation
the fetch fails in flight: rejected, next: fetch 2 same as main in flight: fetch 2, next: fetch 2
the fetch fails, the new module loaded first new: fetch 2, in flight: rejected, next: rejected new: fetch 2, in flight: rejected, next: fetch 2 fetch 2 three times
an import() that joined the fetch of a static import importer fetch 1, import() fetch 1 (evaluated again), next: fetch 1 both fetch 1, next: fetch 2 importer fetch 1, import() fetch 2, next: fetch 2
  1. Which should the overtaken import() get: its module from before the clear (what [JSC] removeEntry() and clearAll() keep the realm's [[LoadedModules]] in step with the registry #748 does for a load that has its entry), or the result of a load started after the clear? And the same when its fetch failed?
  2. With this PR the answer depends on how far the load was. An import() whose own fetch was in flight gets the new module. One whose dependency was in flight keeps its old graph ([JSC] removeEntry() and clearAll() keep the realm's [[LoadedModules]] in step with the registry #748, test/cli/hot/hot.test.ts:827 in Bun). Is that split acceptable?

"Keep its module" is built on the branch robobun/cfa20256/module-load-by-name-detach-after-clear (+233 lines). Two cases that main gets right fail with it:

  • A module in an import cycle: in flight, next and every later import() reject with ReferenceError: Cannot access 'Base' before initialization. until the next save. The old root and the module that the cycle finds under the key are two instances.
  • Bun.serve() in the module, the new module loaded first: the old body runs after the new one and its handler replaces the new handler.

Both are as on main with this PR.

What this PR makes worse than main

  • The second fetch can fail where the first did not (the save removed or renamed the file, or the embedder's fetch hook throws). The import() then rejects. On main it resolved with the old module.
  • The key is the one resolved before the clear. If the save changes what the specifier resolves to, the overtaken import() still loads the old key.
  • The overtaken import() is a root for the new module. Its evaluation can start before the new entry point imports the module in its own order. For a fetch that ended with a module, main does the same with the old module. For a fetch that failed it is new.

Other runs

  • Two clears, the second during the fetch that the load made when it started again: the import() gets the module of the third fetch, and the second is not evaluated. In the stress test, and in Bun (in flight: fetch 3, next: fetch 3, one evaluation).
  • The second fetch throws or rejects: the import() rejects, and nothing stays on the key. A later static import of it fetches and loads.
  • Bun.ModuleGraph#dispose() with an import() in flight: both import() reject with ERR_INVALID_STATE as on main. The graph fetches the module once more.
  • With [JSC] A failed loadModule() stores its error in the registry entry it loaded #754 applied on top (no conflict): both stress tests exit 0, and a module that fails to link after a clear keeps one error object for later import().

Reach

  • bun --hot, an import() that the entry point does not await (a reload waits while the promise of the entry point is pending), and a save while the fetch of that module itself is in flight. The fetch is the read and the transpile of the file.
  • Also Bun.ModuleGraph#dispose(), which calls clearAll().

Not in this PR

Cost

Release builds of Bun at ea6a2c7b7c, with WebKit 274ebb3 (main then) and with this PR's preview build autobuild-preview-pr-853-e301a116. Sizes and instruction counts from llvm-objdump -d of bun-profile:

Function main this PR
JSModuleLoader::loadModule() by name 2896 bytes, 728 instructions 2920 bytes, 730 instructions
runInternalMicrotask() (holds moduleLoadTopSettled) 19063 bytes, 4408 instructions 19360 bytes, 4494 instructions
JSModuleLoader::loadModule() by referrer 555 bytes, 144 instructions the same instructions
JSModuleLoader::hostLoadImportedModule() 9155 bytes, 2176 instructions the same instructions
ModuleLoadingContext::create(), both overloads 353 and 393 bytes, 102 and 109 instructions the same instructions
text of bun 107,094,269 bytes 107,094,589 bytes (+320)
  • A load by name that nothing overtook runs 8 of the added instructions. loadModule() by name has 4: it loads the epoch before fetch(), keeps it on the stack, and stores it into the context. moduleLoadTopSettled has 4: two loads, a compare and a branch that is not taken. The other added instructions are the block that starts the load again.
  • ModuleLoadingContext keeps its size (the static_assert in its constructor). Only loadModule(name) writes the field, so the context of a static import is made by the same instructions as before. JSModuleLoader keeps its 136 bytes: the epoch is in padding.
  • The referrer that loadModule(name) hands to the embedder's fetch() is not kept for the second load. Neither Bun's hook nor the shell's reads it.

Bun half

The pin bump and the tests (test/cli/hot/hot.test.ts) follow the answer. The rows above are from that branch. A Bun debug build with this PR's preview build passes them, and the hot, isolation, plugin, mock, resolve, node:module and module-graph suites.

@robobun

robobun commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status: draft. It waits for the answer to the question in #754 (comment).

How to reproduce

  • Engine: jsc -m JSTests/stress/module-load-by-name-in-flight-when-registry-cleared.js exits 0 on this branch. On main's runtime with the shell function of this PR it exits 3 (expected 2 but got 1).
  • Bun: run bun --hot entry.mjs with the two files below. main prints in flight: fetch 1, evaluation 1 and next: fetch 1, evaluation 1. A Bun build on this branch prints fetch 2, evaluation 1 on both lines.
entry.mjs and a.mjs

a.mjs:

export {};

entry.mjs:

import { readFileSync, writeFileSync } from "node:fs";
globalThis.runs = (globalThis.runs ?? 0) + 1;
if (globalThis.runs === 1) {
  globalThis.fetches = 0;
  Bun.plugin({
    name: "hold the module's own load open until the reload",
    setup(build) {
      build.onLoad({ filter: /a\.mjs$/ }, () => {
        const fetch = ++globalThis.fetches;
        const loaded = { contents: "export const fetch = " + fetch + "; export const evaluation = (globalThis.evaluations = (globalThis.evaluations ?? 0) + 1);", loader: "js" };
        if (globalThis.moduleMayLoad) return loaded;
        const { promise, resolve } = Promise.withResolvers();
        globalThis.moduleMayLoad = () => resolve(loaded);
        writeFileSync(import.meta.path, readFileSync(import.meta.path));
        return promise;
      });
    },
  });
  globalThis.inFlight = import("./a.mjs");
} else {
  globalThis.moduleMayLoad();
  try {
    const show = m => "fetch " + m.fetch + ", evaluation " + m.evaluation;
    console.log("in flight:", show(await globalThis.inFlight));
    console.log("next:", show(await import("./a.mjs")));
    process.exit(0);
  } catch (error) {
    console.log("rejected:", error);
    process.exit(1);
  }
}

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Preview build of e301a11: autobuild-preview-pr-853-e301a116

clearAll() takes every module out of the registry while loads are in
flight. A load that has its entry goes on with that entry, and
finishLoadingImportedModule() keeps its record out of the realm's
[[LoadedModules]] (#748). A load by name (loadModule(name): import(), an
entry point) has no entry until its fetch settles, so the clear cannot take
it out. When the fetch settles, moduleLoadTopSettled calls provideFetch() by
key and registers what was fetched before the clear in the registry of
after it:

    const inFlight = import("./a.js");   // the fetch of a.js is pending
    loader.clearAll();                   // the embedder reloads
    await inFlight;
    await import("./a.js");              // the module from before the clear

In Bun that is a hot reload while an import() is fetching its module: the
program keeps the old file until the next save. When the fetch fails
instead, the error of the old file rejects the import() and is stored on
the module that the key holds by then.

The loader now has a registry epoch that clearAll() advances. A load by name
keeps the epoch it started under (taken before fetch(), which can run
script). When its fetch settles under another epoch, moduleLoadTopSettled
does not use what the fetch settled with, a source or an error. It calls
loadModule() by name again and the first load settles with the second. The
second load is a load made after the clear in every respect: it joins the
module the key holds or fetches, it has its own epoch, and a fetch of its
own that fails is not kept on the key.

What a load that has its entry at the clear does is not changed.

A load that no clear overtook pays the copy of the epoch and one compare.
ModuleLoadingContext keeps its size: the epoch is in the padding after
m_step. Only loadModule(name) sets it, so the context of a static import
costs what it did. hostLoadImportedModule() is not changed.

registryEpoch() is public for an embedder that publishes a fetch by key in
tables of its own (Bun's require cache).

clearModuleRegistry() in the jsc shell calls clearAll(), for the new test.

* JSTests/stress/module-load-by-name-in-flight-when-registry-cleared.js: Added.
* JSTests/stress/resources/module-load-by-name-in-flight-when-registry-cleared/.gitignore: Added.
* Source/JavaScriptCore/jsc.cpp:
* Source/JavaScriptCore/runtime/JSMicrotask.cpp:
* Source/JavaScriptCore/runtime/JSModuleLoader.cpp:
* Source/JavaScriptCore/runtime/JSModuleLoader.h:
* Source/JavaScriptCore/runtime/ModuleLoadingContext.cpp:
* Source/JavaScriptCore/runtime/ModuleLoadingContext.h:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant