Runtime Async Feature

[TheAngryByrd]

Description

Fixes #19056

This was 99% written by Oh-My-Opencode planner/executor with Opus 4.6. I'm not claiming it's good but it did make it work.

docs/samples/runtime-async-library/README.md is where to look at how to run the sample library.

Checklist

• Test cases added

• Performance benchmarks added in case of performance changes

• Release notes entry updated:

  Please make sure to add an entry with short succinct description of the change as well as link to this pull request to the respective release notes file, if applicable.

  Release notes files:

  • If anything under src/Compiler has been changed, please make sure to make an entry in docs/release-notes/.FSharp.Compiler.Service/<version>.md, where <version> is usually "highest" one, e.g. 42.8.200
  • If language feature was added (i.e. LanguageFeatures.fsi was changed), please add it to docs/release-notes/.Language/preview.md
  • If a change to FSharp.Core was made, please make sure to edit docs/release-notes/.FSharp.Core/<version>.md where version is "highest" one, e.g. 8.0.200.

  Information about the release notes entries format can be found in the documentation.
  Example:

  • More inlines for Result module. (PR #16106)
  • Correctly handle assembly imports with public key token of 0 length. (Issue #16359, PR #16363)
    *while! (Language suggestion #1038, PR #14238)

  If you believe that release notes are not necessary for this PR, please add NO_RELEASE_NOTES label to the pull request.

[github-actions]

❗ Release notes required

@TheAngryByrd,

Caution

No release notes found for the changed paths (see table below).

Please make sure to add an entry with an informative description of the change as well as link to this pull request, issue and language suggestion if applicable. Release notes for this repository are based on Keep A Changelog format.

The following format is recommended for this repository:

* <Informative description>. ([PR #XXXXX](https://github.com/dotnet/fsharp/pull/XXXXX))

See examples in the files, listed in the table below or in th full documentation at https://fsharp.github.io/fsharp-compiler-docs/release-notes/About.html.

If you believe that release notes are not necessary for this PR, please add NO_RELEASE_NOTES label to the pull request.

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

Change path	Release notes path	Description
src/FSharp.Core	docs/release-notes/.FSharp.Core/11.0.100.md	No release notes found or release notes format is not correct
src/Compiler	docs/release-notes/.FSharp.Compiler.Service/11.0.100.md	No release notes found or release notes format is not correct
LanguageFeatures.fsi	docs/release-notes/.Language/preview.md	No release notes found or release notes format is not correct

[majocha]

This is maybe the one thing that makes me uneasy.
This introduces a special case of something like a type-driven return type conversion.
I wonder if it would be possible to have a special function instead, let's say:

val __asyncReturn: 't -> Task<'t>

compiled to no-op or whatever dotnet expects for the async runtime feature.

[T-Gro]

As public API in FSharp.Core ?

[majocha]

I guess so, similar to current StateMachineHelpers. Although I gave no thought how this should behave with ns20.

[majocha]

I don't like very much that the feature resides at the level of computation expressions.
IMO it should be possible to write a working low-level runtime async method using dotnet's AsyncHelpers and some FSharp.Core helpers. Ideally runtime async CEs should compile to such code without any special treatment in CheckComputationExpressions.fs. I don't know if it's possible.

[T-Gro]

IMO worth updating from main (this is freshly added) and doing a fast enum check:
#19394

[T-Gro]

[<Agentic-Review>] Missing runtime feature check — only language version is gated, not RuntimeFeature.Async

checkLanguageFeatureAndRecover is called here but checkLanguageFeatureRuntimeAndRecover is never called for RuntimeAsync.

InfoReader.fs:860 correctly defines isRuntimeFeatureAsyncSupported and maps RuntimeAsync to it at line 927, but this check is never invoked anywhere in the compiler.

A user targeting netstandard2.0 with --langversion:preview can use [<MethodImpl(0x2000)>] without a compile-time error. The method gets the 0x2000 IL flag but the runtime doesn't understand it — runtime failure instead of compile-time error.

Compare with DefaultInterfaceMemberConsumption and InterfacesWithAbstractStaticMembers which DO call checkLanguageFeatureRuntimeAndRecover (ConstraintSolver.fs:3684, MethodCalls.fs:1260, MethodOverrides.fs:369,985).

Suggested fix — add after this line:

checkLanguageFeatureRuntimeAndRecover cenv.infoReader LanguageFeature.RuntimeAsync mBinding

[T-Gro]

[<Agentic-Review>] ExprContainsAsyncHelpersAwaitCall false-positive for Expr.Obj overrides

This function walks into Expr.Obj override bodies (the overrides and iimpls lists), but object expression overrides compile as separate IL methods via GenObjectExprMethod. They are NOT part of the enclosing method's IL body — the enclosing method just emits I_newobj.

If an Await call appears in an object expression override, the enclosing method would incorrectly get 0x2000. This is inconsistent with Expr.Lambda which correctly returns false at line ~9284 ("Lambda bodies become separate closure classes").

Additionally, the overrides themselves never get body-analysis 0x2000 (they aren't Val bindings processed by GenMethodForBinding), so we'd get a double fault: wrong method marked, correct method unmarked.

Suggested fix:

| Expr.Obj (_, _, _, basecall, _, _, _) ->
    check basecall  // only basecall is part of the enclosing method's IL

[T-Gro]

[<Agentic-Review>] Architectural gap: tail-call suppression not applied for body-analysis async methods

hasAsyncImplFlagEarly (line ~9444) only detects explicit [<MethodImpl(0x2000)>], so eenvForMeth.withinSEH stays false for methods that get 0x2000 via body analysis (ExprContainsAsyncHelpersAwaitCall at line ~9594). Since the IL body is generated before body analysis runs, CanTailcall (line 4533: not withinSEH) may return Tailcall for calls in tail position.

Validated that AsyncHelpers.Await calls are independently protected by makesNoCriticalTailcalls=true (line 5462 for non-virtual IL calls), so the suspension points themselves won't get tail. prefix. Only F# function calls after all Await points could theoretically get tail. — low practical risk with current builders (sample library Run is non-inline).

Suggested defense-in-depth fix — hoist the body-analysis check before IL codegen:

let bodyContainsAwait =
    not hasNoDynamicInvocation && returnsTaskLikeType
    && ExprContainsAsyncHelpersAwaitCall body
let eenvForMeth =
    if hasAsyncImplFlagEarly || bodyContainsAwait then
        { eenvForMeth with withinSEH = true }
    else eenvForMeth

[T-Gro]

[<Agentic-Review>] Closure return type fallback always wraps as Task<T>, never ValueTask<T>

This fallback path uses mkWoNullAppTy g.system_GenericTask_tcref [returnTy] — always Task<T>, regardless of the builder's actual return type. A builder using ValueTask<T> would get the wrong closure base class.

The primary path (declaredRetTyOpt at lines ~7110-7123) correctly preserves the original Task/ValueTask type, so this only fires when declaredRetTyOpt is None AND the body has Await calls — a rare edge case. But worth a // TODO or handling ValueTask<T> for completeness.

[T-Gro]

[<Agentic-Review>] Sentinel adds real runtime overhead; consider setting cloIsAsync directly in IlxGen

AsyncHelpers.Await(ValueTask.CompletedTask) is described as a "no-op at runtime" but it IS a real method call — ValueTask.CompletedTask creates a struct, Await checks IsCompleted, returns. In a tight while loop each iteration pays this cost. The optimizer marks TOp.ILCall as having side effects, so it cannot eliminate the sentinel even when redundant.

An alternative approach: set cloIsAsync = true directly in IlxGen.GenClosureTypeDefs based on whether the enclosing CE builder has [<RuntimeAsync>], without injecting any sentinel. The typed tree flows through IlxGen with full type info — the builder attribute is accessible there.

If keeping the sentinel approach, consider at minimum suppressing the debug point (see next comment) and documenting the per-invocation cost.

[T-Gro]

[<Agentic-Review>] Sentinel debug point not suppressed — debugger may stop on invisible no-op

SynExpr.Sequential here uses DebugPointAtSequential.SuppressNeither. The debug infrastructure may emit a sequence point for the sentinel. A user stepping through code could land on the invisible AsyncHelpers.Await(ValueTask.CompletedTask).

Compare with line ~1537 where the WhileBang internal rewrite uses SuppressBoth for synthetic sequential expressions.

Use SuppressBoth or at minimum SuppressStmt to suppress the sentinel half.

[T-Gro]

[<Agentic-Review>] builderHasRuntimeAsync called 6 times per CE without caching

This function does tryTcrefOfAppTy + TryFindFSharpAttribute on every call, and is invoked at 6 separate Delay injection points within a single CE translation. Since ceenv.builderTy never changes during CE translation, the result is invariant for the entire CE.

Consider caching the result in ceenv at construction time:

type CompExprTranslationEnv = {
    ...
    isRuntimeAsync: bool
}

This eliminates 5 redundant attribute lookups per CE.

[T-Gro]

[<Agentic-Review>] DiscardErrorsLogger silences all diagnostics during return type re-resolution

TcTypeOrMeasure is called with DiscardErrorsLogger, which suppresses ALL diagnostics — not just the expected "unknown type parameter" errors. If a genuine error exists in the return type annotation (e.g. misspelled type name), it would be swallowed here.

Because the SynExpr.Typed wrapper is stripped by stripTypedFromInnermostLambda, the annotation is never re-checked via TcExprTypeAnnotated. For non-recursive bindings where the Val type starts as a fresh inference variable, this creates a diagnostic gap.

Consider replacing with a targeted catch of the specific recoverable exception, or at minimum adding a comment documenting why discarding all errors is safe in this position.

[T-Gro]

[<Agentic-Review>] Fallback path creates disconnected domain types

When TcTypeOrMeasure fails (retTyOpt = None), this fallback creates NEW inference types via NewInferenceType g that are disconnected from overallPatTy. Unlike the primary path (lines ~11402-11408) which creates shared domainTys, unifies them with overallPatTy via UnifyTypes, then reuses them in bodyTy — this fallback:

1. Never calls UnifyTypes to pre-unify overallPatTy
2. Creates fresh domain types not shared with the Val's declared type
3. Strips SynExpr.Typed (line 11424) so the annotation is not re-checked

For generic methods like Run<'T>(f: unit -> 'T) : Task<'T>, the 'T in the parameter type and return type may not unify through the body type.

Consider either: (a) not stripping SynExpr.Typed in the fallback and letting normal type-checking handle it, or (b) performing pre-unification analogous to the primary path.

[T-Gro]

[<Agentic-Review>] InlineIfLambda bypass allows a no-op attribute without warning

This isRuntimeAsyncMember check bypasses the InlineIfLambda diagnostic for runtime-async methods. However, for non-inline runtime-async methods (ValInline.Never from ComputeInlineFlag at CheckExpressions.fs:2458), InlineIfLambda has no semantic effect — the optimizer never inlines such methods, so lambda arguments are never substituted inline.

For inline runtime-async methods (ValInline.Always), v.ShouldInline = true so inlined = true and the check passes WITHOUT needing this bypass.

The bypass silently allows users to write [<InlineIfLambda>] on parameters of non-inline methods with no effect — this is misleading. Consider removing the bypass and letting the existing warning inform users, or updating the comment to explain why this is intentional.

[T-Gro]

[<Agentic-Review>] String-based AsyncHelpers detection is fragile and triplicated

This is the first of three copies of the same magic-string matching:

1. Here in Optimizer.fs:exprContainsAsyncHelpersAwait (lines ~2343-2345)
2. IlxGen.fs:ExprContainsAsyncHelpersAwaitCall (lines ~9269-9272)
3. IlxGen.fs:ilBodyContainsAsyncHelpersAwait (lines ~6698-6703)

All three hard-code "System.Runtime.CompilerServices.AsyncHelpers" and method names "Await", "AwaitAwaiter", "UnsafeAwaitAwaiter".

Risks:

• A user creating their own type named AsyncHelpers with an Await method would trigger false-positive inlining suppression
• If the BCL adds new overloads, all three must be updated
• Any typo in one copy silently breaks the check in that location

Consider extracting a shared isAsyncHelpersAwaitMethod predicate into a common location.

Also: this version walks through Expr.Lambda bodies (line 2355), unlike IlxGen.ExprContainsAsyncHelpersAwaitCall which returns false at lambda boundaries (line ~9284). This means higher-order functions returning async closures (let makeCallback () = fun () -> Await(...)) are unnecessarily blocked from cross-module inlining. The inner closure gets its own IL method with its own 0x2000 flag — the outer function does not need to be blocked.

[T-Gro]

[<Agentic-Review>] Inline RuntimeAsync methods bypass cut — correctness depends on IlxGen propagation

ValInline.Always methods bypass the cut function entirely (line ~4226: if vref.ShouldInline || vref.InlineIfLambda then einfo), so the exprContainsAsyncHelpersAwait check never fires for them. Their full CurriedLambdaValue body — including Await calls — is exported for cross-module inlining.

Correctness depends on IlxGen's body-analysis path (line ~9594) propagating 0x2000 to the consumer function. This works IF:

1. The consumer returns a Task-like type (returnsTaskLikeType check), AND
2. The consumer is NOT marked NoDynamicInvocation

If a consumer does not return a Task-like type but has Await calls inlined into it (edge case), the 0x2000 flag will not be set and the Await calls will fail at runtime.

Consider adding a diagnostic or assertion when an inline RuntimeAsync member's body is inlined into a non-Task-returning context.

[T-Gro]

[<Agentic-Review>] Error 3887 (tcRuntimeAsyncNotSupported) is defined but never emitted

grep -rn 'tcRuntimeAsyncNotSupported' src/Compiler/**/*.fs returns zero hits. This error is defined here and translated in 13 .xlf files but no compiler code path emits it. Dead code adding translation burden.

Either wire it up at a call site (e.g., 0x2000 on properties, constructors, abstract members) or remove it.

[T-Gro]

[<Agentic-Review>] Error codes 3884-3887 break numeric ordering

These new codes (3884-3887) appear at lines 1812-1815, BEFORE existing codes 3880-3883 at lines 1816-1819. FSComp.txt maintains monotonically increasing error codes by convention. Reorder so 3880-3883 come first, then 3884-3887.

[T-Gro]

[<Agentic-Review>] No .fsi signature file for new FSharp.Core public API

RuntimeAsyncAttribute is a permanent public type in Microsoft.FSharp.Control, but neither runtimeAsync.fs nor runtimeTasks.fs has a corresponding .fsi signature file. FSharp.Core convention uses .fsi files to define the public API contract explicitly (see async.fs/async.fsi, tasks.fs/tasks.fsi, resumable.fs/resumable.fsi).

[T-Gro]

[<Agentic-Review>] If shipped in FSharp.Core, RuntimeTaskBuilder needs [<RuntimeAsync>]

Currently this code is never compiled — FSharp.Core targets netstandard2.0/netstandard2.1, so NET10_0_OR_GREATER is never set. But if net10.0 is ever added as a TFM for FSharp.Core:

1. RuntimeTaskBuilder lacks [<RuntimeAsync>], so builderHasRuntimeAsync (CheckComputationExpressions.fs:90) would return false — no sentinel injection into Delay closures
2. Run uses RuntimeTaskBuilderUnsafe.cast (f()) — a raw (# "" a : 'b #) reinterpret cast from 'T to Task<'T> — which is only safe when the 0x2000 async flag is active and the runtime wraps the return value
3. Run is member inline with [<MethodImpl(0x2000)>], and the Delay returns 'T not unit -> Task<'T> (contrast with the sample library builder which returns unit -> Task<'T>)

For runtimeTask { return 42 } with this builder: after inlining Run/Delay/Return, the consumer body is cast(42) with no Await calls, so no 0x2000 flag, so the raw cast executes without runtime-async wrapping — undefined behavior.

The sample library builder at docs/samples/.../RuntimeTaskBuilder.fs correctly has [<RuntimeAsync; Sealed>] and uses a non-inline Run with AsyncHelpers.Await(f()). Consider either:

• Adding [<RuntimeAsync>] here and redesigning to match the sample library pattern
• Or removing this prototype if the sample library is the canonical design

[T-Gro]

[<Agentic-Review>] Test coverage gaps for runtime-async

Several important scenarios have zero test coverage:

1. No test for actual async suspension (HIGH)
All behavioral tests use Task.FromResult / Task.CompletedTask / ValueTask.FromResult — already-completed tasks that never suspend. No test verifies correct suspension/resumption when awaiting a genuinely delayed task. This is the core value proposition of runtime-async.

Suggested test:

[<MethodImpl(enum<MethodImplOptions> 0x2000)>]
let actualSuspension() : Task<int> =
    AsyncHelpers.Await(Task.Delay(50))
    42
// Verify: t.Result = 42 (after real async suspension)

2. No negative test for error 3886 — tcRuntimeAsyncCannotReturnByref (HIGH)
Error 3886 is emitted at CheckExpressions.fs:11498 but has zero test coverage.

3. No cancellation test (HIGH)
No test verifies CancellationToken / TaskCanceledException propagation through runtime-async methods.

4. No test for ValueTask<T> or ValueTask as declared method return type (HIGH)
All methods return Task<int> or Task. Error 3884 accepts ValueTask/ValueTask<T> — should have positive coverage.

5. No IL test verifying tail-call suppression (MEDIUM)
Runtime spec forbids tail. prefix in 0x2000 methods. No verifyIL test checks for absence of tail. instructions.