Insert a set of known types and methods references necessary for async thunks into the mutable module #121679

jtschuster · 2025-11-16T04:10:28Z

Async thunk IL uses types that may not have MethodRef or TypeRef tokens in the assembly being crossgen'ed. There are some assertions to validate that any references in "faux il" version with the assembly, which isn't true for these types and methods. To work around this, we can inject these references into the mutable module, a synthetic module added to the assembly for things like this. During initialization, this adds all the known necessary types and methods. There is still the issue of AsyncMethodVariant.GetTypicalMethodDefinition not resolving to an EcmaMethod, so we aren't able to enable compiling any async methods yet.

… emit the IL

Copilot

Pull Request Overview

This PR adds infrastructure to insert references for known types and methods required by async thunks into the mutable module. This is preparatory work for supporting async methods in ReadyToRun compilation, though async method compilation remains disabled due to unresolved issues with AsyncMethodVariant.GetTypicalMethodDefinition.

Key Changes

Added AddingReferencesToR2RKnownTypesAndMethods flag to MutableModule to allow adding references to known async-related types/methods
Implemented InitializeKnownMethodsAndTypes() to populate known async-related types and methods from System.Private.CoreLib into the mutable module
Updated assertion logic to handle references to these known types/methods that exist outside the version bubble
Added early exit for async variant methods in compilation (they remain unsupported for now)
Refactored AsyncThunks.cs to declare exception type earlier for use in catch region definition

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/coreclr/tools/aot/ILCompiler.ReadyToRun/TypeSystem/Mutable/MutableModule.cs	Added `AddingReferencesToR2RKnownTypesAndMethods` flag and updated assertion to allow references during async type/method initialization
src/coreclr/tools/aot/ILCompiler.ReadyToRun/JitInterface/CorInfoImpl.ReadyToRun.cs	Added early exit for async variants and updated token resolution logic to handle known mutable module types/methods
src/coreclr/tools/aot/ILCompiler.ReadyToRun/ILCompiler.ReadyToRun.csproj	Added project references to async stub files (AsyncThunks.cs, AsyncResumptionStub.cs and related files)
src/coreclr/tools/aot/ILCompiler.ReadyToRun/IL/ReadyToRunILProvider.cs	Added resolver parameter to InitManifestMutableModule and removed assertion that blocked async variants
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRunCodegenNodeFactory.cs	Updated InitManifestMutableModule call to pass the Resolver parameter
src/coreclr/tools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs	Implemented InitializeKnownMethodsAndTypes() to populate known async types/methods and added helper methods to check if types/methods are in the known set
src/coreclr/tools/Common/TypeSystem/IL/Stubs/AsyncThunks.cs	Moved exception type declaration earlier to be accessible for catch region creation

Copilot · 2025-11-16T04:20:14Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+                    if (_compilationModuleGroup.VersionsWithMethodBody((EcmaMethod)method))
+                        continue;
+
+                    EntityHandle ? handle = _manifestMutableModule.TryGetEntityHandle(method);


There is inconsistent spacing in the nullable type declaration. Line 515 uses EntityHandle? handle (no space before ?), but this line has EntityHandle ? handle (with a space before ?). The space should be removed for consistency.

Suggested change

EntityHandle ? handle = _manifestMutableModule.TryGetEntityHandle(method);

EntityHandle? handle = _manifestMutableModule.TryGetEntityHandle(method);

jkotas · 2025-11-16T07:02:07Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+                        throw new NotImplementedException($"Entity handle for known method ({method}) not found in manifest module");
+
+                    var token = new ModuleToken(_manifestMutableModule, handle.Value);
+                    this.AddModuleTokenForMethod(method, token);


Does this mean that every R2R image is going to have metadata for references to all async helpers?

We should be creating these metadata tokens lazily, only when the async helper is actually used.

jkotas · 2025-11-16T07:08:58Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+            knownMethods.Add(asyncHelpers.GetKnownMethod("ValueTaskFromException"u8, new MethodSignature(MethodSignatureFlags.Static, 0, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "ValueTask"u8), new TypeDesc[] { exception })));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("TaskFromException"u8, new MethodSignature(MethodSignatureFlags.Static, 1, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "Task`1"u8).MakeInstantiatedType(CompilerContext.GetSignatureVariable(0, method: true)), new TypeDesc[] { exception })));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("ValueTaskFromException"u8, new MethodSignature(MethodSignatureFlags.Static, 1, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "ValueTask`1"u8).MakeInstantiatedType(CompilerContext.GetSignatureVariable(0, method: true)), new TypeDesc[] { exception })));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("FinalizeTaskReturningThunk"u8, new MethodSignature(MethodSignatureFlags.Static, 0, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "Task"u8), Array.Empty<TypeDesc>())));


Given that this is somewhat setting the names of these methods in stone, we should make sure that they have good names, following the same principles we use to name public APIs.

I would expect that a method called FinalizeFoo is going to take Foo as an argument. It is not what this method does. This can use a better name.

jkotas · 2025-11-16T07:09:25Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+            knownMethods.Add(asyncHelpers.GetKnownMethod("CompletedTaskResult"u8, null));
+
+            // ExecutionAndSyncBlockStore type and methods
+            var executionSyncBlockStore = CompilerContext.SystemModule.GetKnownType("System.Runtime.CompilerServices"u8, "ExecutionAndSyncBlockStore"u8);


Similar here - ExecutionAndSyncBlockStore does not look like a great name to me.

jkotas · 2025-11-16T07:13:23Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

            }
        }
+
+        private ImmutableHashSet<MethodDesc> KnownMethods;


Immutable collections are meant to be used for collections updated in lock-free way. They pay extra overhead for the lock-free nature.

If you just a have a hashtable that gets initialized once and then just used for lookups, regular HashSet is going to work just fine and be faster.

jkotas · 2025-11-16T07:17:07Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+            knownTypes.Add(asyncHelpers);
+
+            knownMethods.Add(asyncHelpers.GetKnownMethod("AsyncCallContinuation"u8, null));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("TaskFromException"u8, new MethodSignature(MethodSignatureFlags.Static, 0, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "Task"u8), new TypeDesc[] { exception })));


We may want to have some correct-by-construction scheme that guarantees that this list captures all methods used by the thunk IL emitters.

E.g. have an enum for all these methods and make sure that the thunk IL emitters get the method reference via the ID. It is going to guarantee that we do not forget to add the method here as we are changing the emitters.

jkotas · 2025-11-16T07:27:45Z

This is effectively creating an alternative scheme for encoding ReadyToRunHelper (

runtime/src/coreclr/inc/readytorun.h

Line 307 in 0b9d2cc

enum ReadyToRunHelper

).

I expect that we will use it for encoding higher-level helpers outside async too. For example, it would be fairly natural to use it to encode READYTORUN_HELPER_GetCurrentManagedThreadId that is an alias for Environment.CurrentManagedThreadId method.

jkotas · 2025-11-16T08:05:27Z

...ools/aot/ILCompiler.ReadyToRun/Compiler/DependencyAnalysis/ReadyToRun/ModuleTokenResolver.cs

+            knownMethods.Add(asyncHelpers.GetKnownMethod("FinalizeTaskReturningThunk"u8, new MethodSignature(MethodSignatureFlags.Static, 1, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "Task`1"u8).MakeInstantiatedType(CompilerContext.GetSignatureVariable(0, method: true)), Array.Empty<TypeDesc>())));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("FinalizeValueTaskReturningThunk"u8, new MethodSignature(MethodSignatureFlags.Static, 1, CompilerContext.SystemModule.GetKnownType("System.Threading.Tasks"u8, "ValueTask`1"u8).MakeInstantiatedType(CompilerContext.GetSignatureVariable(0, method: true)), Array.Empty<TypeDesc>())));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("TransparentAwait"u8, null));
+            knownMethods.Add(asyncHelpers.GetKnownMethod("CompletedTask"u8, null));


CompletedTask makes sense as a name for a property that returns completed Task. It does not make sense as a name for a method that consumes completed task.

jtschuster added 3 commits November 15, 2025 18:21

Add known methods that may be unreferenced into the MutableModule.

3dfcffa

Only add types and methods outside of the version bubble, still can't…

13f7d1d

… emit the IL

Fix extra changes

d638752

jtschuster requested review from davidwrighton, eduardo-vp and jkotas November 16, 2025 04:10

jtschuster requested a review from MichalStrehovsky as a code owner November 16, 2025 04:10

Copilot AI review requested due to automatic review settings November 16, 2025 04:10

github-actions bot added the area-crossgen2-coreclr label Nov 16, 2025

dotnet-policy-service bot assigned jtschuster Nov 16, 2025

Copilot started reviewing on behalf of jtschuster November 16, 2025 04:11 View session

Copilot finished reviewing on behalf of jtschuster November 16, 2025 04:14

Copilot AI reviewed Nov 16, 2025

View reviewed changes

jkotas reviewed Nov 16, 2025

View reviewed changes

build-analysis bot mentioned this pull request Nov 16, 2025

AF: *(_UNCHECKED_OBJECTREF *)handle == NULL (HndCreateHandle called by getJitHandleForObject) #117138

Open

jkotas reviewed Nov 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Insert a set of known types and methods references necessary for async thunks into the mutable module #121679

Insert a set of known types and methods references necessary for async thunks into the mutable module #121679

jtschuster commented Nov 16, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 16, 2025

Uh oh!

jkotas Nov 16, 2025

Uh oh!

jkotas Nov 16, 2025 •

edited

Loading

Uh oh!

jkotas Nov 16, 2025 •

edited

Loading

Uh oh!

jkotas Nov 16, 2025 •

edited

Loading

Uh oh!

jkotas Nov 16, 2025

Uh oh!

jkotas commented Nov 16, 2025

Uh oh!

jkotas Nov 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	EntityHandle ? handle = _manifestMutableModule.TryGetEntityHandle(method);
	EntityHandle? handle = _manifestMutableModule.TryGetEntityHandle(method);

Insert a set of known types and methods references necessary for async thunks into the mutable module #121679

Are you sure you want to change the base?

Insert a set of known types and methods references necessary for async thunks into the mutable module #121679

Conversation

jtschuster commented Nov 16, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkotas Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

jkotas commented Nov 16, 2025

Uh oh!

jkotas Nov 16, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jkotas Nov 16, 2025 •

edited

Loading

jkotas Nov 16, 2025 •

edited

Loading

jkotas Nov 16, 2025 •

edited

Loading