Enable runtime async via compiler intrinsics

[majocha]

Add preview F# compiler support for .NET runtime-async methods. Compiler-recognized __runtimeAsyncReturn intrinsics mark Task/ValueTask methods and lambdas with MethodImplOptions.Async, while AsyncHelpers.Await* calls become runtime suspension points.

The optimizer preserves and specializes inline suspension fragments, rewrites suspending exception handlers and finally compensations, and reports unsupported byref or suspension patterns. The feature is gated by langversion:preview and target-runtime metadata support; FSharp.Core exposes the intrinsics only for net10.0, with builders remaining application-defined.

---

Consider an inline "sync" CE builder. applying __runtimeAsyncReturn to the inlined code in its Run method compiles the computation expression into a single runtime async method:

member inline _.Run([<InlineIfLambda>] code) = __runtimeAsyncReturn(code())

Resumption is handled by the runtime, calling AsyncHelpers.Await in Bind is all that is needed to make the resulting CE async:

member inline _.Bind(task, [<InlineIfLambda>] continuation) = AsyncHelpers.Await task |> continuation

runtime spec :
Runtime-async specification

interesting docs and links:

• Runtime-async code-generation contract
• Roslyn runtime async design
• 11 preview 7 changes
• Roslyn - Test Plan for Runtime Async
• Runtime async streams
  To do:

• decide on naming
• design and implement other allowed return types (ValueTask<_> and unit versions)
• awaits in EH blocks (IAsyncDisposable) - handled by rewriting the block to take suspensions outside
• byref locals not preserved across suspension - added diagnostic
• use of AsyncHelpers suspending methods outside of runtime async - added diagnostic
• handle --optimize- (debug configuration)
• fixed (pinned) locals not preserved across suspension - needs separate codepath
• implement IAsyncEnumerable, low level production and consumption
• test debug stepping / stack traces - tested manually, they are not great
• test AsyncLocals propagation
• add sample low level implementation of IAsyncEnumerable
• implement sample asyncSeq builder
• implement YieldFromFInal handover in asyncSeq
• update ildasm - separate PR, because of bulk baseline changes
• runtime async iterators - built-in prototype

[github-actions]

❗ Release notes required

You can open this PR in browser to add release notes: open in github.dev

---

✅ Found changes and release notes in following paths:

Change path	Release notes path	Description
`src/FSharp.Core`	docs/release-notes/.FSharp.Core/11.0.100.md
`src/Compiler`	docs/release-notes/.FSharp.Compiler.Service/11.0.100.md
`src/Compiler/Facilities/LanguageFeatures.fsi`	docs/release-notes/.Language/preview.md

[majocha]

Another thing to think through is inlining. Currently there are no checks at all for use of suspending AsyncHelpers members outside of an async method. According to spec, this is illegal but the idea is that any AsyncHelpers.Await calls should be contained by or inlined into the resulting async method (see the sample runtimeTask builder in the tests here). It seems to get an efficient single method from a CE the builder needs to declare every method inline and make use of InlineIfLambda.

Currently it is up to the "expert" user to not misuse AsyncHelpers. Ideally the compiler should check for any such illegal calls only after inlining.

This is still a sketch, but it successfully compiles runtimeTask builder. The builder passes ported Tasks.fs tests, which is promising.

[T-Gro]

Ideally the compiler should check for any such illegal calls only after inlining.

We could have a notion of PostIlxGen checks.
Agree it must run after all optimizations.

[majocha]

Looks like the runtime feature is quickly evolving, see #19056 (comment)

runtime-async-tiering-and-tail-await-optimizations

[majocha]

I wonder how to support the other allowed return types.

__runtimeAsyncReturn<'T>       : 'T -> Task<'T>
__runtimeAsyncReturnValueTask<'T> : 'T -> ValueTask<'T>
__runtimeAsyncReturnUnit       : unit -> Task
__runtimeAsyncReturnValueTaskUnit : unit -> ValueTask

and it quickly becomes a whole zoo. Do we need the non-generic versions at all? Only for potential C# interop, I guess. The upside is that the current type check is all we need to keep it correct, without any extra handling.

The other alternative it to have a unconstrained __runtimeAsyncReturn: 'T -> 'Carrier and do extra checks that the 'Carrier type is supported.

[majocha]

Unfortunatelly to make async iterators like TaskSeq implementable efficiently, we still need resumable state machine. In fact we need to extend it to generate a runtime-async MoveNext. It would allow to do runtime-async AsyncHelpers.Await directly in a state machine step.

See:

https://github.com/dotnet/roslyn/blob/features/runtime-async-streams/docs/compilers/CSharp/Runtime%20Async-Streams%20Design.md

[majocha]

AI thoughts on runtime async state machines implementation:
https://gist.github.com/majocha/785b8cf30de031eec340cc4227e93061

[T-Gro]

🤖🕵️ Rechecked at 4dd3acc9.

Legend: checked = verified fixed; unchecked = partially fixed.

• Stack allocation
• Late byref capture
• Curried evaluation order
• Synchronized rejection
• Fixture assertions
• Duplicate FS3917
• reraise
• Callback construction effects
• Preview gating
• Debug surface baseline
• Feature-off performance

Remaining details and examples

Imports and test harness omitted.

reraise — throws outer, not inner, after suspension.

__runtimeAsyncReturn (
    try raise outer
    with _ ->
        AsyncHelpers.Await gate
        try raise inner
        with _ -> reraise ())

Callback construction — executes twice instead of once.

let mutable constructed = 0
let inline twice ([<InlineIfLambda>] f: unit -> int) =
    __runtimeAsyncReturn (f () + f ())

let run () =
    twice (constructed <- constructed + 1; fun () -> 21)

Calling run leaves constructed = 2. An unused-callback variant leaves it at 0. The opaque effect() control passes.

Preview gate — this compiles and emits runtime-async code under F# 9.

// --langversion:9 --optimize-
let f x = x |> __runtimeAsyncReturn

(f 42).Result returns 42; expected FS3350. Optimization enabled correctly rejects it.

Nested ordinary seq — synchronous MoveNext contains an illegal Await.

__runtimeAsyncReturn (
    seq {
        let value = AsyncHelpers.Await gate
        yield value
        yield value + 1
    })

With an incomplete gate, enumeration throws NullReferenceException. Expected FS3916, not an async conversion of ordinary seq.

Imported pin lifetime — rejected locally, accepted across assemblies.

// Library.dll
let inline comparePin (array: byte[]) ([<InlineIfLambda>] action) =
    use before = fixed array
    action ()
    use after = fixed array
    struct (NativePtr.toNativeInt before, NativePtr.toNativeInt after)

// Consumer.dll
__runtimeAsyncReturn (comparePin data (fun () -> AsyncHelpers.Await gate))

After suspension and compacting GC, the addresses differ: the pin did not survive. The witness never dereferences a stale address.

Debug baseline: original intrinsic omissions fixed; eight other entries remain missing.

Performance: bounded optimized task/seq A/B measured +6.6% optimizer time; not a general performance claim.

Cross-assembly inlining: the new test passes, but consumer IL still contains the inlined body. It does not verify the claimed restriction.

[github-actions]

🔍 Tooling Safety Check — Affects-Bootstrap, Affects-Build-Infra, Affects-Compiler-Output, Affects-Test-Tooling
Affects-Bootstrap: Compiler source changes alter bootstrap compiler behavior.
Affects-Build-Infra: FSharp.Core project changes alter build inputs.
Affects-Compiler-Output: Optimizer and codegen changes alter emitted IL.
Affects-Test-Tooling: Shared SurfaceArea utility changes verification behavior.

Generated by PR Tooling Safety Check · gpt56 966.4K · ◷

[majocha]

Handling the very edgy case of pinned locals is problematic:

// Library.dll
let inline comparePin (array: byte[]) ([<InlineIfLambda>] action) =
    use before = fixed array
    action ()
    use after = fixed array
    struct (NativePtr.toNativeInt before, NativePtr.toNativeInt after)

// Consumer.dll
__runtimeAsyncReturn (comparePin data (fun () -> AsyncHelpers.Await gate))

We could preserve the isPinning flag in metadata but that does not solve the problem fully. Older assemblies will not have this flag. What then? Reject inlining from older libraries altogether? A more general compiler warning when inlining into runtime-async method?

This is downstream from the design decision to not make the concept of inline runtime-async code fragment explicit. The implicit assumption is that any inline function may contain runtime suspensions (AsyncHelpers awaits).