A logical ReadyToRun (R2R) module is distributed across a primary WebAssembly module and one or more auxiliary WebAssembly modules.
Loading the primary module makes the logical R2R module functional and usable. Methods whose compiled code has not yet arrived remain callable through R2R-to-interpreter thunks. Auxiliary modules can arrive later, after which their methods are activated incrementally.
The runtime supports N RUNTIME_FUNCTION tables per logical R2R module, with one table per physical Wasm file.
This design currently supports single-threaded hosting only. Auxiliary-module installation and method activation run on the runtime's single execution thread. Multithreaded hosting is outside the scope of this design.
The primary module defines an active data segment large enough to hold all relevant data for the logical module, including data supplied by auxiliary modules.
Regions whose contents belong exclusively to auxiliary modules are initially filled with zeros. The primary module may therefore remain large in uncompressed physical size, but these zero-filled regions should compress very well.
The primary module contains:
- All string-referenced thunks.
- An active element segment defining all logically callable methods in the complete R2R composition.
MethodDefEntryPointsandInstanceMethodEntryPointsfor the complete composition.
Function-table slots for methods implemented in auxiliary modules initially contain the appropriate R2R-to-interpreter thunks. This allows calls from existing R2R code to dispatch correctly before the auxiliary code is available.
For a method implemented in an auxiliary module, its normal required fixup list is replaced by a special auxiliary-module marker identifying the module that holds its compiled code. The marker is recognized as the method's first fixup.
The method entry encodes its primary-module-relative function-table index. The portable entrypoint (PEP) uses the corresponding slot in the primary module's table as its invoke target.
Installing that index for a deferred method must preserve the PEP's interpreter preference. This requires a deferred-target update operation distinct from the existing PortableEntryPoint::SetActualCode, which clears interpreter preference.
| Auxiliary-module state | Method-loading behavior |
|---|---|
Loaded (INITIALIZED_FLAG is 1 or 2) |
Find the method's fixup list through the auxiliary-module metadata and activate the method synchronously, including its required direct-call dependencies. Clear interpreter preference only after activation is complete. |
Not loaded (INITIALIZED_FLAG is 0) |
Install the encoded function-table index while retaining interpreter preference, add the MethodDesc to the deferred-activation list, and increment the auxiliary module's REQUEST_COUNT. If the new count is 1, call OnAuxiliaryModuleRequest. |
Methods first discovered after module arrival use the synchronous loaded-module path; they are not added to the deferred queue.
Each auxiliary module imports:
- The primary module's memory and function table.
- The primary module's base memory address and base table index.
For future flexibility, auxiliary modules may also import functions from the primary module, such as R2R helpers or commonly called managed methods.
Each auxiliary module exports ActivateModule. This export installs the module's data and control-function pointers, marks the auxiliary module as loaded, and indicates that deferred initialization work remains.
Internally, the auxiliary module maintains a function table containing the compiled methods and their funclets that can be installed into the primary module's table.
Metadata for each auxiliary module resides at a well-defined location in the primary module.
| Field | Meaning |
|---|---|
| Filename RVA | RVA of the string naming the auxiliary module. |
ActivateR2RTableIndex function-table index |
Slot for the auxiliary module's activation function. Initially points to a placeholder function that returns 0. |
AuxiliaryModuleFixupList RVA |
RVA of the auxiliary module's method-fixup lookup structure. |
| First method table index | Primary-module-relative table index of the first slot assigned to the auxiliary module. |
MethodCount |
Number of runtime-function slots assigned to the auxiliary module, including funclet slots. Defines the number of entries in its RUNTIME_FUNCTION table and the length of its contiguous function-table range. |
Auxiliary RUNTIME_FUNCTION table RVA |
RVA of that physical module's runtime-function table. The table contains MethodCount records. |
INITIALIZED_FLAG |
Initialization state, described below. |
REQUEST_COUNT |
Initially 0; incremented when R2R metadata identifies a method in this auxiliary module as required. |
INITIALIZED_FLAG |
State |
|---|---|
0 |
Auxiliary module has not been loaded. |
1 |
Auxiliary module is loaded; deferred fixup processing remains. |
2 |
The module is loaded and its deferred-activation queue is drained. This does not mean that every method in the module has been activated. |
Methods discovered in state 2 are activated synchronously, so their discovery does not reopen the deferred queue or change the module back to state 1.
Each auxiliary module's contiguous table range has a one-to-one correspondence with its local RUNTIME_FUNCTION records, including funclets:
auxiliaryRelativeIndex =
primaryModuleRelativeTableIndex - firstMethodTableIndex
actualFunctionTableIndex =
primaryModuleTableBase + primaryModuleRelativeTableIndex
auxiliaryRuntimeFunctionIndex = auxiliaryRelativeIndex
auxiliaryRelativeIndex must be in [0, MethodCount). It is also the zero-based lookup key in AuxiliaryModuleFixupList; funclet slots do not require independent managed-method activation entries.
The host, probably JavaScript, calls the auxiliary module's ActivateModule export. That export performs the following steps:
-
Copy passive data into the primary module's reserved memory. Initially, this includes the auxiliary
RUNTIME_FUNCTIONtable, portions of the fixup data not supplied by the primary module, and the auxiliary methods' fixup lists. -
Install auxiliary control-function pointers into the primary module's function table. Their slots are recorded in the auxiliary-module metadata. The initially expected control function is:
int ActivateR2RTableIndex(int primaryModuleRelativeTableIndex);
Calling this function installs the selected method's R2R implementation and its associated funclet entries into the primary module's table.
-
Make the auxiliary runtime-function table and its VirtualIP mapping available to the runtime, then set
INITIALIZED_FLAGto1. The loaded state is published only after the copied data and control-function entries are ready.
The runtime processes the list of methods whose R2R implementations should be initialized.
Auxiliary method-fixup lists use the same lookup arrangement as MethodDefEntryPoints, except that the lookup key is the auxiliary-module-relative function-table index, rather than a MethodDef RID.
To activate a method, the runtime:
- Marks the method as activation-in-progress and resolves its required fixups, including the transitive fixup dependencies of methods it calls directly.
- Ensures that the required direct-call dependency closure is ready, then calls the auxiliary module's
ActivateR2RTableIndexfunction to install the compiled implementation and its associated funclets. - Publishes the completed activation and clears the PEP's interpreter preference. Compiled dispatch must not become available before the required fixups and callable entries are ready.
The same activation procedure is used for methods discovered synchronously after the auxiliary module has loaded.
Completed methods, including dependencies completed during synchronous activation, are removed from any outstanding deferred-activation queue.
Activating method A must also complete the required fixups for any method B that A calls directly, even if B was not independently requested.
The runtime tracks per-method activation state: not activated, activation-in-progress, and activated. Encountering an activation-in-progress dependency records the dependency rather than recursively restarting its activation.
Mutually dependent methods, such as A calling B and B calling A, are completed as an activation group. Their internal direct-call references may be established during fixup processing, but the group is not published for ordinary dispatch until all members' fixups and required dependencies are ready.
Activation may be expensive. The runtime may process a subset of deferred methods, resume normal execution, and return later to process more. A JavaScript-side timer is one possible driver for this incremental work.
Once a loaded module's deferred-activation queue is drained, its INITIALIZED_FLAG becomes 2. Methods in other modules that have not yet loaded do not prevent this transition.
The compiler must decide which methods belong in the primary module and which belong in auxiliary modules.
The initial implementation supports a hot/cold split:
- A PGO- or heuristic-selected hot set goes into the primary module.
- Remaining methods go into a single auxiliary module.
For demonstration purposes, the initial heuristic can classify helpers and public non-generic methods as hot, with everything else classified as cold. This is not intended as a long-term heuristic; it is intended to demonstrate that the mechanism works.
The design also permits future arrangements such as:
- Hot/warm/cold modules.
- A hot primary module plus per-assembly auxiliary modules.
Auxiliary modules use indexed filenames, for example:
app.r2r.1.wasm
app.r2r.2.wasm
READYTORUN_FIXUP_MethodEntry_ReadyToRun already requests target-method fixup processing. Its handling must be extended so that success for a direct-call target guarantees the required activation dependency closure is ready, rather than merely establishing an interpreter fallback. This can perform fixup work ahead of an independent request for the target method.
Direct calls within an auxiliary module are permitted subject to this activation dependency-closure requirement.
Direct calls from the auxiliary module to the primary module may be done by doing an call_indirect with the known index of the target method. (Future work could optimize this to use a typed function reference function table, but for now this will work)
Direct calls from 1 auxiliary module to another are not supported.
The compiler must:
- Split the
RUNTIME_FUNCTIONtable into per-physical-module tables. - Arrange function-table indices so that the primary module's R2R methods are contiguous and each auxiliary module's R2R methods occupy a contiguous range.
- Include funclet slots in each auxiliary module's
MethodCountand preserve the one-to-one correspondence between that range and its localRUNTIME_FUNCTIONrecords. - Generate R2R-to-interpreter thunks for every signature shape needed to populate auxiliary-method slots.
The compiler must identify memory regions belonging to auxiliary modules and communicate that ownership to the Wasm module writers.
This data partitioning is technically optional for correctness: fully populating the primary module's data would still work. However, reducing the primary module's data size is a goal of this design.
The compiler must also:
- Generate auxiliary-module metadata at a well-known location discoverable by the runtime.
- Adjust code-generation rules so auxiliary code can be loaded safely.
- Retain IL for any method assigned to an auxiliary module.
A logical R2R module can have multiple RUNTIME_FUNCTION tables. An auxiliary module's table becomes eligible for lookup when its INITIALIZED_FLAG is at least 1.
MethodCount, including funclet slots, defines the length of the auxiliary table.
The runtime recognizes an auxiliary-module marker in the first fixup of a method. If the module has not loaded, it updates the PEP's function-table index without clearing interpreter preference and records the method for deferred activation. If the module has loaded, it activates the method synchronously.
Both paths clear interpreter preference only after the method's required fixups, direct-call dependencies, and callable entries are ready.
CoreCLR exposes:
int DoRuntimeDeferredModuleActivationWork(int methodsToProcess);The argument specifies how many methods' worth of work to process. The return value counts only remaining activation work for loaded auxiliary modules.
Deferred methods belonging to modules that have not loaded are excluded from this count. A return value of 0 means there is no remaining activation work for currently loaded modules; it does not mean that all auxiliary modules have arrived or that every method in them has been activated.
The runtime detects loaded auxiliary modules and uses this entrypoint to advance their deferred initialization.
When an auxiliary module's REQUEST_COUNT changes from 0 to 1, a hosting hook notifies the host that a method from that module has been requested.
CoreCLR calls
void OnAuxiliaryModuleRequest(const char *auxModuleName, int moduleBase, int functionTableBase);
The hook supplies the primary module's base table index and base memory offset which should be enough to identify the base module to get the exported memory/table from, and instantiate. As we allow for direct calls between modules there may be a more complex import/export scheme we have to build, but for now, lets hold off on that.
The JavaScript host must:
- Trigger auxiliary-module downloads, either in response to the hosting notification or through another download policy.
- Instantiate each auxiliary module with the required imports.
- Call that module's
ActivateModuleexport. - Call
DoRuntimeDeferredModuleActivationWorkin batches, yielding to normal execution between batches, until it returns0for the currently loaded modules.
When another auxiliary module arrives, repeat the installation and activation-work sequence for the newly available work.
Note
This document was formatted and edited from the supplied design text by GitHub Copilot.