feat(Async): Add exception-unwrapping Await

[bartelink]

Implements Async.Await for Task, Task<'T>, ValueTask and ValueTask<'T> (aka a polished version of the
community AwaitTaskCorrect implementation). Includes a fallback SRTP based type augmentation that uses the GetAwaiter protocol to support custom waits a la C# await.

Key differentiation from Async.AwaitTask is that AggregateExceptions are unwrapped such that a try ... with <ExceptionType> -> will type-match correctly.

Key distinction from the canonical implementation (which derives from https://www.fssnip.net/7Rc/title/AsyncAwaitTaskCorrect) is that the implementation is intended to have 1:1 matching of all stacktrace preservation properties borne by AwaitTask (and continue to track that over time).

NOTE one key implementation decision is that this PR does NOT attempt to resolve #2127 so:

1. if the computation workflow's CT is cancelled at the point where Await is invoked, normal cancellation semantics as per AwaitTask apply:
   • exception continuation is passed an OperationCanceledException
   • the Task in question's Result will go unobserved
2. if a cancellation of the computation workflow via it's ambient cancellation token is triggered during the course of the Await, it will (like AwaitTask):
   • NOT abort and abandon the observation Task
   • instead, it will wait [as a C# await would] until such time as the Task completes (either successfully, with a fault, or via cancellation)

Checklist

• Test cases added
• Release notes entry updated
• Add documentation cross-links and strongly-implied deprecation flagging conveying that:
  • AwaitTask will always yield an AggregateException
  • Await should be the used in preference for new code
  • Await can technically still propagate an AggregateException

[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

[bartelink]

@T-Gro if you and/or others can give this a quick scan please, I'd like to confirm:

1. nobody else has work in flight (yes, a bit late for that!)
2. the rough approach is viable
3. the key impl decision is reasonable:
   • no attempt to get too clever and have the API react to Async cancellation by abandoning waits, i.e. if you have code that does not propagate Async.CancellationToken to a Task start, Await will hang just as AwaitTask
     • BUT this is OK as abandoning in-flight tasks and/or the controlled disposal of associated resources/compute would not be strictly better
     • It aligns with e.g. how Async.Parallel waits for correct teardown/completion of all in-flight executions before yielding a result and/or completing the honoring of cancellation
   • Best practice recommendation will instead be to use Async.StartTaskImmediate, which will
     • surface the CT
     • include this correctly-unwrapping Await within it's processing
     • see Async/Task interop/cancellation/limits fsharp/fslang-suggestions#1467
4. a rough indication of whether I should leave the xmldoc as is, or attempt to complete the rough tasks I've laid out in the checklist in the OP

TL;DR the overall proposition

1. Await is just AwaitTask with unwrapping, zero other semantic change. => A better default to use where you'd otherwise use AwaitTask
2. Usage of AwaitTask and Await are both smells - can you be sure all Tasks that have been started were correctly wired into the computation tree's CT?
3. In general, usage of Async.Await should be replaced with/migrated to Async.StartTaskImmediate, which surfaces the problem
4. if there was an analyzer flagging Async.Await/AwaitTask -> Async.StartTaskImmediate migration opportunities, a closely related one would be flagging cases of task { flows that use let! and/or do! bindings against Async<'T>) rather than using Task.startAsyncImmediate (which forces passing a CT to Async.StartImmediateAsTask

CC @TheAngryByrd @gusty @njlr who have provided useful feedback/review on stuff in this space in recent times

[Copilot]

Pull request overview

Adds a new Async.Await API to FSharp.Core for Task/Task<'T> (and ValueTask/ValueTask<'T> on netstandard2.1) that unwraps “egregious” single-inner AggregateExceptions so exception matching works as expected, while aiming to preserve existing AwaitTask stacktrace behavior.

Changes:

• Implement Async.Await in async.fs by sharing the existing AwaitTask continuation machinery and selectively unwrapping single-inner AggregateExceptions.
• Expand unit tests to exercise both AwaitTask and Await behavior (including AggregateException cases) and add ValueTask coverage under #if NETSTANDARD2_1.
• Update FSharp.Core surface area baseline (partially) and add a release-notes entry.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncType.fs	Converts many tests to run against both AwaitTask and new Await; adds new behavior-focused tests for AggregateException unwrapping and ValueTask.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl	Adds Async.Await entries for netstandard2.1 Debug surface area baseline.
src/FSharp.Core/async.fsi	Updates AwaitTask XML docs and adds new Async.Await API docs (including ValueTask overloads under netstandard2.1).
src/FSharp.Core/async.fs	Implements Async.Await and refactors task-await internals to optionally unwrap single-inner AggregateExceptions.
docs/release-notes/.FSharp.Core/11.0.100.md	Adds release note entry for new Async.Await.

[majocha]

I'm thinking about naming. Async.Await name does not suggest that it applies to Tasks only. Since it is already 4 times overloaded, maybe it makes sense to add an overload working with any awaitable, to have parity with C#? This can be discussed and done separately from this PR, of course. (Also SRTP can be a can of worms).

[bartelink]

maybe it makes sense to add an overload working with any awaitable, to have parity with C#? This can be discussed and done separately from this PR, of course. (Also SRTP can be a can of worms).

@majocha Yes, this was already part of the brief as per the comment from @dsyme.

I'd personally need to research what it would entail, so if you or anyone wants to contribute an impl, feel free to hang a PR off this one.

But bottom line I agree it would be good for the support for tasklike things to be done either as part of this PR or as a very fast follow so the world only needs to validate the overloading works out cleanly once.

[bartelink]

I'd personally need to research what it would entail, so if you or anyone wants to contribute an impl, feel free to hang a PR off this one.

. @majocha Added a commit:

• as demonstrated by the test, the GetResult() already unwraps, so it would seem to me that doing deeper integration with the internals of the specific-type overloads won't have any benefit
• open question is whether all 4 overloads of the existing implementations are still earning their keep in terms of:
  • perf and allocations (Benchmark tests are probably the real answer to that)
  • extending platform reach (does the GetAwaiter protocol work for downlevel TFMs?)

[T-Gro]

One last review round.

[T-Gro]

UnsafeOnCompleted skips ExecutionContext capture/restore; the typed overloads flow it via ContinueWith.

type Wrapper<'T>(t: Task<'T>) = member _.GetAwaiter() = t.GetAwaiter()
let al = AsyncLocal<string>()
async { al.Value <- "trace-id"
        let! _ = Async.Await(Wrapper someIncompleteTask)
        return al.Value }

• typed Async.Await → "trace-id"
• this SRTP overload → null
• lost: AsyncLocal, Activity.Current, logging scopes

Verified at BCL level: UnsafeOnCompleted runs the continuation with the completing thread's context; OnCompleted captures at subscribe and restores. The awaiter is :> ICriticalNotifyCompletion : INotifyCompletion, so:

-                    (awaiter :> ICriticalNotifyCompletion)
-                        .UnsafeOnCompleted(fun () ->
+                    (awaiter :> INotifyCompletion)
+                        .OnCompleted(fun () ->

[bartelink]

Applied (and regression test added)
Aside: given that ICriticalNotifyCompletion is now no longer being used, the type expectation could drop to INotifyCompletion (though that would be inconsistent with every other SRTP await helper we have)

[T-Gro]

Multi-inner faults surface differently depending on which Async.Await binds:

let tcs = TaskCompletionSource<int>()
tcs.SetException [ ArgumentException(); InvalidOperationException() ]
Async.Await tcs.Task              // typed
Async.Await (Wrapper tcs.Task)    // SRTP

• typed → AggregateException (UnwrapExn unwraps only Count=1)
• SRTP → ArgumentException (raw GetResult(), first inner)

Full alignment isn't possible for arbitrary awaiters, so just document it — append to the SRTP <remarks> in async.fsi:

  /// with <c>IsCompleted</c> and <c>GetResult()</c> members. Exceptions thrown by <c>GetResult()</c> are
- /// propagated directly.
+ /// propagated directly. Unlike the <see cref="T:System.Threading.Tasks.Task"/> overloads, an
+ /// <see cref="T:System.AggregateException"/> carrying multiple inner exceptions is not preserved:
+ /// the first inner exception surfaces (standard <c>GetResult()</c> semantics).

[bartelink]

done.

[T-Gro]

The ambient-cancellation caveat that AwaitTask carries was dropped from the new Await remarks (here and at 847/877/905). Await is the recommended default, and it deliberately ignores the ambient CT (tested at AsyncType.fs:548), so users need this guidance:

  /// If the task is canceled then <see cref="T:System.Threading.Tasks.TaskCanceledException"/> is raised.
+ /// Note the task may be governed by a different cancellation token to the overall async computation;
+ /// normally start it with the token from <c>let! ct = Async.CancellationToken</c>, and catch
+ /// <see cref="T:System.Threading.Tasks.TaskCanceledException"/> where the overall async is started.

[bartelink]

Done with some rewording in e1d0708.

This text should also reference Async.StartTaskImmediate when that lands.

[T-Gro]

I noticed I was owing a few replies here, I apologize for taking a longer time.

the key impl decision is reasonable: no attempt to get too clever and have the API react to Async cancellation by abandoning waits [...]

Agreed, and worth stating explicitly beyond the approval: deferring #2127 and matching AwaitTask/Async.Parallel teardown (wait for the task, don't abandon it) is the right default. One follow-up: the ambient-CT caveat AwaitTask carries got dropped from the new Await remarks — please restore it (inline note on async.fsi:816), since Await is now the recommended default.

open question is whether all 4 overloads of the existing implementations are still earning their keep [...] does the GetAwaiter protocol work for downlevel TFMs?

Keep all four. The concrete overloads give stacktrace parity, ExecutionContext preservation, and multi-inner AggregateException fidelity that the SRTP path doesn't (inline notes on async.fs:2294 and :2289). And the SRTP/GetAwaiter path is TFM-agnostic (ICriticalNotifyCompletion exists on ns2.0), so it's the only ns2.0 ValueTask route. Complementary, not redundant — benchmarks can size the perf delta but won't change that.

Let me know if any of the other questions from earlier are still open on your side — happy to pick up anything I've skipped.

[bartelink]

Let me know if any of the other questions from earlier are still open on your side — happy to pick up anything I've skipped.

Thanks @T-Gro for the great review work - I should get around to addressing them all in the next few days and will @ you on any follow-ups

[bartelink]

@T-Gro Thanks for the thorough review, and especially for catching the erroneous UnsafeOnCompleted

Let me know if any of my doc changes overreach

One potential clone noted: #19785 (comment)

Please mark any threads as resolved; I'll address any follow-ups you desire later and/or tomorrow