Use external method thunks for Wasm R2R virtual dispatch

[davidwrighton]

Summary

Enable ReadyToRun class-virtual calls on CoreCLR browser-Wasm to use the existing external-method import thunk and fixup pathway, then dynamically publish a signature-compatible vtable-dispatch portable entrypoint at the callsite.

The first invocation enters the ordinary WasmImportThunk and ExternalMethodFixupWorker. For eligible class-virtual calls, the worker resolves the receiver's restored vtable slot, prepares the selected method for R2R calls, looks up the matching V thunk in the existing dynamic thunk table, allocates a virtual-dispatch portable entrypoint from the module loader allocator, and atomically publishes it. Subsequent calls load the selected target portable entrypoint through packed vtable offsets. If that target has not yet been prepared, the thunk substitutes the original import portable entrypoint and re-enters the normal external-method fixup path. Both paths share one final call_indirect.

Wasm no longer receives the JIT's VirtualStubCell hidden argument. The portable entrypoint already identifies the dispatch cell, and retaining the extra argument made the managed callsite signature incompatible with the generated thunk, including in tail-call position.

The generated code is shared at two levels:

• Dispatch imports reuse ordinary method-import delay-load thunk code when their rich managed lowering signatures match.
• Virtual-dispatch thunks are keyed only by the actual Wasm function type. Managed distinctions that lower identically, such as an indirect structure argument and an i32 argument on Wasm32, share one V thunk.

Non-generic virtual methods declared on generic types use this path, including calls from shared generic code whose exact context requires a runtime lookup. Interfaces, arrays, and true generic virtual methods continue to use the existing LDVIRTFTN path.

Validation

Built the Release browser CoreCLR runtime and regenerated the browser test layout:

.\build.cmd clr -os browser -c Release
src\tests\build.cmd browser Release -GenerateLayoutOnly /p:LibrariesConfiguration=Release

The focused R2RTestSuites.WasmVirtualDispatch test passes. It validates:

• ordinary class-virtual dispatch;
• non-generic virtual methods on generic owning types;
• unconstrained and constrained class-virtual calls from shared generic code;
• exclusion of true generic virtual methods;
• delay-load thunk sharing between compatible dispatch and method imports;
• one canonical V thunk for an indirect structure argument and a pointer-sized argument;
• generated vtable lookup, unresolved-target fallback, and forwarded call_indirect sequences.

The existing JIT\opt\virtualstubdispatch\mixed test was expanded to cover multiple receiver types, a virtual method on a generic owning type, and ABI-equivalent indirect-structure and pointer-sized virtual signatures. It passes under Node.js after Crossgen2 compilation:

PASS
Expected: 100
Actual: 100

Steady-state virtual-call throughput

An ad hoc Node.js harness measured no-inline virtual calls between R2R-compiled functions. The managed DLL was identical for baseline and final; each build's Crossgen2 produced its own Wasm R2R image. Startup was excluded. Each process calibrated approximately one-second samples, performed three full warmups, forced a full GC before each measured sample, and recorded 12 samples per scenario. Three process rounds alternated baseline/final ordering, producing 36 samples per result.

Scenario	Baseline median	Final median	Latency reduction	Throughput increase
Monomorphic	51.54 ns/call (19.40 M calls/s)	20.78 ns/call (48.13 M calls/s)	59.68%	148.02% (2.48x)
Bimorphic, alternating receiver types at one callsite	50.83 ns/call (19.67 M calls/s)	20.85 ns/call (47.96 M calls/s)	58.98%	143.79% (2.44x)

Sample standard deviations were 0.32 ns baseline / 0.28 ns final for monomorphic calls and 0.09 ns baseline / 0.04 ns final for bimorphic calls.

Wasm image size

Sizes compare matched clean Release browser CoreCLR builds at the current merge base, 80a8cdbdb9c36ccab97374afcb2f0491ae58a94d, and PR tip 020406010b645e209604cf0c7a183b179512a30a. Both builds used:

.\build.cmd clr -c Release -os browser -rebuild

Section sizes are Wasm section payload sizes; total is the filesystem length.

Metric	Merge base	PR tip	Delta
System.Private.CoreLib.wasm total	29,217,785 bytes	29,074,862 bytes	-142,923 bytes (-0.49%)
Wasm CODE	14,535,667 bytes	14,408,164 bytes	-127,503 bytes (-0.88%)
Wasm DATA	9,138,266 bytes	9,137,546 bytes	-720 bytes (-0.01%)
Wasm name	5,296,804 bytes	5,281,737 bytes	-15,067 bytes (-0.28%)

Note

This pull request description was generated with GitHub Copilot.

[azure-pipelines]

Azure Pipelines:
Successfully started running 6 pipeline(s).
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/crossgen-contrib
See info in area-owners.md if you want to be subscribed.

[Copilot]

🔵 Needs a closer look

It changes Wasm behavior across VM fixup, JIT calling conventions, Crossgen2 codegen, and the R2R format, so a maintainer should validate subtle ABI and runtime invariants before merge.

Pull request overview

This PR enables CoreCLR browser-Wasm ReadyToRun class-virtual calls to go through the existing external-method import thunk/fixup path, and then publishes a signature-compatible vtable-dispatch portable entrypoint that forwards subsequent calls via packed vtable offsets.

Changes:

• Add a new Wasm “V” (virtual-dispatch) thunk kind and codegen for forwarding virtual calls via vtable offsets stored in a dynamically published portable entrypoint.
• Extend CoreCLR’s ExternalMethodFixupWorker (Wasm) to publish a virtual-dispatch portable entrypoint after resolving eligible class-virtual fixups.
• Update JIT / R2R call classification to route only eligible Wasm virtuals through stub-dispatch, keeping interfaces/arrays/generic-context cases on the existing LDVIRTFTN path, plus add targeted test coverage.

File summaries

File	Description
src/tests/JIT/opt/virtualstubdispatch/mixed/mixed.cs	Expands the existing JIT test to exercise a single class-virtual callsite with multiple receiver types (via a no-inline wrapper).
src/coreclr/vm/wasm/helpers.hpp	Declares GetVirtualDispatchThunk for looking up pregenerated signature-specific vtable-dispatch thunks.
src/coreclr/vm/wasm/helpers.cpp	Factors portable-entrypoint thunk lookup to accept a prefix and implements GetVirtualDispatchThunk using the new V prefix.
src/coreclr/vm/prestub.cpp	On Wasm, publishes a READYTORUN_VIRTUAL_DISPATCH_PORTABLE_ENTRYPOINT during external method fixup for eligible class-virtual calls.
src/coreclr/vm/method.cpp	Updates the comment on EnsurePortableEntryPointIsCallableFromR2R to reflect its new callsite (R2R virtual dispatch fixup).
src/coreclr/vm/cgensys.h	Minor whitespace-only cleanup around ExternalMethodFixupWorker declaration.
src/coreclr/tools/Common/Compiler/ObjectWriter/WasmInstructions.cs	Adds Wasm instruction encodings/helpers needed by the virtual-dispatch thunk (i32.eqz, i32.load16_u).
src/coreclr/tools/aot/ILCompiler.ReadyToRun/JitInterface/CorInfoImpl.ReadyToRun.cs	Refines Wasm call-kind selection to allow stub-dispatch only for eligible class-virtual calls; updates related assertions/comments.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj	Includes the new WasmVirtualDispatchThunkNode.cs in the build.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRunCodegenNodeFactory.cs	Adds a Wasm virtual-dispatch thunk node cache and ensures DispatchImports entry sizing supports Wasm’s needs.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/WasmVirtualDispatchThunkNode.cs	New node that emits the signature-specific Wasm thunk that performs vtable-based portable-entrypoint dispatch and fallback.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/WasmImportThunkPortableEntrypoint.cs	Removes the assertion that previously rejected virtual-call imports on Wasm.
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/WasmImportThunk.cs	Allows virtual-call imports on Wasm, and adds a dependency to ensure the corresponding V thunk is generated when needed.
src/coreclr/tools/aot/ILCompiler.ReadyToRun.Tests/TestCases/Webcil/WasmVirtualDispatch.cs	New Wasm-focused test input that creates a straightforward virtual dispatch pattern.
src/coreclr/tools/aot/ILCompiler.ReadyToRun.Tests/TestCases/R2RTestSuites.cs	Adds a Wasm-only R2R validation that checks thunk registration and expected instruction sequences in the emitted Wasm body.
src/coreclr/jit/morph.cpp	On Wasm, stops adding the VirtualStubCell hidden argument for stub-dispatch calls.
src/coreclr/jit/importercalls.cpp	Updates commentary clarifying that only some Wasm virtual calls route through LDVIRTFTN now.
src/coreclr/inc/readytorun.h	Defines READYTORUN_VIRTUAL_DISPATCH_PORTABLE_ENTRYPOINT (Wasm-only) to carry the V thunk and packed offsets.
docs/design/coreclr/botr/readytorun-format.md	Documents the new V prefix, call flow, and the 12-byte virtual-dispatch portable entrypoint layout.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 0
• Review effort level: Lite

[jkotas]

+67 bytes (+0.0005%)

Why is the code size growth so small? I would expect these thunks to add up to more than just 67 bytes of CODE.

Also, I am wondering whether it would be a better (size) tradeoff to emit call that resolves the target followed by an actual call. We would not need target signature specific virtual dispatch thunks and we can reuse the same shape for interface calls as well.

[davidwrighton]

@jkotas I was actually quite surprised that there was size growth at all. This code is taking logic where we need to do 3 R2R table lookups + 2 indirect calls, into 1 R2R lookup and 1 indirect call. And in fact the size of the normal managed functions DOES shrink by about 77KB .... however, it turns out that by moving to generating virtual method dispatch like we do only other platforms, turned on detection to generate unboxing stubs for ToString, Equals, and GetHashCode implementations on structures. This caused the compiler to find a large number of unboxing stubs that it needed to generate, which is what drove all of the code byte wins to be lost + significant losses in the data size to handle having about 428 new unboxing stubs. (My measurements from before @BrzVlad merged his work to add unboxings stub support to crossgen showed that there was a 0.5% size decrease for Code size, and a slightly smaller increase for Data, yielding an overall size decrease of about 0.15% with this change). The cost of the signature specific thunks is actually very small. Currently we need 67 of them, but my analysis indicates we actually could cut THAT number in half or so by sharing the virtual thunks at the Wasm calling convention level. Also, it appears that we actually generate extra delay-load code when we don't need it. We're generating 62 duplicate copies of delay load code in this PR right now. I'm going to throw this PR back to draft to deal with the excess number of thunks we generate.

In addition there are also a set of other size optimizations that I see that I found in this investigation.

• Generating unboxing stubs with a stub generation pathway instead of the current practice of generating unique unboxing stubs with the jit. This could allow us to probably reduce the current generation of about 1700 unboxing stubs into generating 22 stubs total, which would probably be a fairly nice size savings. Copilot thinks it would save about 2%.
• We also generate a fair amount of code bodies with completely identical code. (Think mostly functions which return false, or just return, or whatnot). We could shrink the wasm file by 3-4% by sharing those. This could be done without impacting behavior in any way.

[azure-pipelines]

Azure Pipelines:
Successfully started running 6 pipeline(s).
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The WASM change to suppress the VirtualStubCell well-known arg conflicts with existing VSD lowering assumptions (asserts/incorrect lowering) and needs coordinated updates before it’s safe to merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It changes VM+JIT+crossgen2 codegen paths for Wasm R2R virtual dispatch, with cross-component correctness implications that require focused human review beyond the single confirmed issue noted.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

There are verified correctness/consistency issues (notably GetVirtualDispatchThunk behavior vs its contract and Wasm array-virtual call routing not matching the PR’s stated design) that should be resolved before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Lite

[jkotas]

Check "WASM R2R runtime tests" for regressions before merging

[Copilot]

🔵 Needs a closer look

Add coverage for the generated thunk body and the unresolved-target fallback path before approval.

Review details

Suppressed comments (2)

src/coreclr/tools/aot/ILCompiler.ReadyToRun.Tests/TestCases/R2RTestSuites.cs:177

• This validation only inspects import metadata and canonical thunk keys; it never inspects or executes the generated WasmVirtualDispatchThunkNode body. A regression in the packed-offset loads, unresolved-target fallback, or forwarded call_indirect arguments would still pass these assertions. Please add bytecode-level checks for those instructions or an executable R2R/Wasm test that exercises the fallback path.

                    Validate = Validate,
                },
            ]));

src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/WasmVirtualDispatchThunkNode.cs:149

• This fallback branch is not behaviorally exercised by the tests added here. R2RTestRunner only compiles and inspects the image, and the mixed test invokes targets that are compiled in the same R2R test assembly, so no test leaves a vtable target PortableEntryPoint with a null code slot and verifies that InitialEntry re-enters the delay-load fixup. Please add a cross-module/non-R2R target case (or equivalent setup) that forces this branch; otherwise a regression here can still pass the current tests and trap on the first call.

[!NOTE] This review comment was generated with GitHub Copilot.

            // Redispatch through the original entrypoint if this receiver's target is not yet callable from R2R.
            expressions.Add(Local.Get(targetCodeLocalIndex));
            expressions.Add(I32.Eqz);
            expressions.Add(Block.If(WasmBlockType.Empty));
            expressions.Add(Local.Get(portableEntrypointLocalIndex));

• Files reviewed: 19/19 changed files
• Comments generated: 0 new
• Review effort level: Lite

[davidwrighton]

/ba-g The test failures are now only in mono which isn't affected by this change. @jkotas could you approve?

[lewing]

it looks like this caused #134144