Skip to content

Let an embedder subclass CompiledWasmModuleHolder - #8101

Merged
floitsch merged 1 commit into
mainfrom
floitsch/wasm-holder-subclassable
Nov 13, 2026
Merged

floitsch merged 1 commit into
mainfrom
floitsch/wasm-holder-subclassable

Conversation

@floitsch

Copy link
Copy Markdown
Contributor

jsg::CompiledWasmModuleHolder (added in #7706) keeps the compiled code of one builtin Wasm module, today Pyodide's pyodide.asm.wasm, alive for its own lifetime, so that every isolate in the process that loads the module instantiates it from the same compiled code instead of compiling it again. ModuleRegistry::addBuiltinModule(), addBuiltinBundle() and the Python module registration take a holder by reference and call getOrCompile() on it whenever an isolate loads the module. The holder guarantees that concurrent callers on any thread get a module compiled with their isolate's Wasm ESM integration builtins setting, compiling at most once per setting except for concurrent first loads.

The holder is a concrete class with a non-virtual getOrCompile() that always keeps the compiled modules in its own two slots. An embedder that keeps compiled Wasm code in a store of its own, such as a process-wide, size-bounded store keyed by content hash that also serves user modules, therefore can't pass an entry of that store to the module registry. It would have to keep a second copy of Pyodide's compiled code in a separate holder, retaining the wire bytes and machine code twice and reporting them outside its store, or change the registry's signatures to accept something other than a holder.

This change makes getOrCompile() virtual and gives the class a virtual destructor, so an embedder can subclass the holder and route getOrCompile() to its own store while the registry APIs stay as they are. The default implementation is unchanged, and so is every existing caller. The class comment now states the contract an override has to keep: it may be called concurrently from any thread, and it returns a module compiled with the calling isolate's setting.

The cost is one virtual call per module load, next to a Wasm instantiation, and a subclass still carries the base class's two unused slots (two empty mutex-guarded kj::Maybes). The existing holder test in modules-new-test ("CompiledWasmModuleHolder keeps compiled code after its isolate is gone") continues to cover the default path. Cloudflare's runtime will use the subclass to keep Pyodide's interpreter pinned in a process-wide store of compiled Wasm modules.

🤖 Generated with Claude Code

@codecov-commenter

codecov-commenter commented Oct 30, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.52%. Comparing base (195c9e9) to head (865393e).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #8101   +/-   ##
=======================================
  Coverage   66.52%   66.52%           
=======================================
  Files         783      783           
  Lines      200816   200816           
  Branches    31414    31414           
=======================================
  Hits       133592   133592           
  Misses      48824    48824           
  Partials    18400    18400           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@floitsch
floitsch marked this pull request as ready for review October 30, 2026 13:08
@floitsch
floitsch requested review from a team as code owners October 30, 2026 13:08

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of c7f9fe58.

This review, of 96e86f12

✅ Approved — A small, backward-compatible change that makes the holder subclassable. No findings.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code reviewer: ✅ LGTM

No issues found in src/workerd/jsg/modules.h. Existing callers are unaffected, and the virtual destructor with noexcept(false) follows KJ convention.


Reviewed commit: 96e86f12

@floitsch
floitsch force-pushed the floitsch/wasm-holder-subclassable branch from 96e86f1 to c7f9fe5 Compare November 5, 2026 14:15

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 0b0510d4.

This review, of c7f9fe58

✅ Approved — Small, backward-compatible change to src/workerd/jsg/modules.h with no findings.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

getOrCompile() is now virtual and the destructor is virtual with noexcept(false), following KJ convention. Existing callers are unaffected.


Reviewed commit: c7f9fe58

@floitsch
floitsch force-pushed the floitsch/wasm-holder-subclassable branch from c7f9fe5 to 0b0510d Compare November 11, 2026 15:51

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 90382dbc.

This review, of 0b0510d4

✅ Approved — One-file change in src/workerd/jsg/modules.h that makes getOrCompile() virtual and adds a virtual destructor. It leaves existing behavior unchanged, and I found no issues.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

getOrCompile() is now virtual and the destructor is virtual with noexcept(false), following KJ convention. The new class comment states the contract for overrides. Existing callers are unaffected.


Reviewed commit: 0b0510d4

@floitsch
floitsch force-pushed the floitsch/wasm-holder-subclassable branch from 0b0510d to 90382db Compare November 12, 2026 16:22

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 865393e7.

This review, of 90382dbc

✅ Approved — One-file change in src/workerd/jsg/modules.h that makes getOrCompile() virtual and adds a virtual destructor. It leaves existing behavior unchanged, and I found no issues.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

getOrCompile() is now virtual and the destructor is virtual with noexcept(false), following KJ convention. The new class comment states the contract for overrides. Existing callers are unaffected.


Reviewed commit: 90382dbc — same changes as 0b0510d4, so this is that commit's review (no new review was run; line numbers are as of 0b0510d4)

Make getOrCompile() virtual, with a virtual destructor, so that an
embedder can keep the compiled code of a builtin Wasm module (Pyodide's
interpreter) in its own process-wide store, shared with other modules,
and still pass it to ModuleRegistry::addBuiltinModule() and the Python
module registration. The default implementation is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@floitsch
floitsch force-pushed the floitsch/wasm-holder-subclassable branch from 90382db to 865393e Compare November 13, 2026 19:22

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — One-file change in src/workerd/jsg/modules.h that makes getOrCompile() virtual and adds a virtual destructor. It leaves existing behavior unchanged, and I found no issues.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

getOrCompile() is now virtual and the destructor is virtual with noexcept(false), following KJ convention. The new class comment states the contract for overrides. Existing callers are unaffected.


Reviewed commit: 865393e7 — same changes as 0b0510d4, so this is that commit's review (no new review was run; line numbers are as of 0b0510d4)

@floitsch
floitsch enabled auto-merge (squash) November 13, 2026 20:00
@floitsch
floitsch merged commit b2ab1d0 into main Nov 13, 2026
36 of 38 checks passed
@floitsch
floitsch deleted the floitsch/wasm-holder-subclassable branch November 13, 2026 20:07
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.

4 participants