feat(Async): Add exception-unwrapping Await

Author: bartelink

docs/release-notes/.FSharp.Core/11.0.100.md

@@ -2,3 +2,7 @@
 
 * Fix `Array.exists2` documentation examples to use equal-length arrays; the previous examples would throw `ArgumentException` at runtime instead of returning the documented `false`/`true` values. ([PR #19672](https://github.com/dotnet/fsharp/pull/19672))
 * Move `Async.StartChild` to the "Starting Async Computations" docs category alongside `Async.StartChildAsTask`. ([Issue #19667](https://github.com/dotnet/fsharp/issues/19667))
+
+### Added
+
+* Add `Async.Await`, which mirrors `Async.AwaitTask` semantics, but elides egregious `AggregateException` wrapping. ([Language Suggestion #840](https://github.com/fsharp/fslang-suggestions/issues/840), [PR #19785](https://github.com/dotnet/fsharp/pull/19785))

src/FSharp.Core/async.fs

@@ -1210,16 +1210,30 @@ module AsyncPrimitives =
 
         task
 
+    // Used by Async.Await path to elide egregious AggregateException wrapping
+    [<DebuggerHidden>]
+    let UnwrapExn (exn: AggregateException) =
+        if exn.InnerExceptions.Count = 1 then
+            exn.InnerExceptions[0]
+        else
+            exn
+
     // Call the appropriate continuation on completion of a task
     [<DebuggerHidden>]
-    let OnTaskCompleted (completedTask: Task<'T>) (ctxt: AsyncActivation<'T>) =
+    let OnTaskCompleted unwrap (completedTask: Task<'T>) (ctxt: AsyncActivation<'T>) =
         assert completedTask.IsCompleted
 
         if completedTask.IsCanceled then
             let edi = ExceptionDispatchInfo.Capture(TaskCanceledException completedTask)
             ctxt.econt edi
         elif completedTask.IsFaulted then
-            let edi = ExceptionDispatchInfo.RestoreOrCapture completedTask.Exception
+            let e =
+                if unwrap then
+                    UnwrapExn completedTask.Exception
+                else
+                    completedTask.Exception
+
+            let edi = ExceptionDispatchInfo.RestoreOrCapture e
             ctxt.econt edi
         else
             ctxt.cont completedTask.Result
@@ -1229,14 +1243,20 @@ module AsyncPrimitives =
     // the overall async (they may be governed by different cancellation tokens, or
     // the task may not have a cancellation token at all).
     [<DebuggerHidden>]
-    let OnUnitTaskCompleted (completedTask: Task) (ctxt: AsyncActivation<unit>) =
+    let OnUnitTaskCompleted unwrap (completedTask: Task) (ctxt: AsyncActivation<unit>) =
         assert completedTask.IsCompleted
 
         if completedTask.IsCanceled then
             let edi = ExceptionDispatchInfo.Capture(TaskCanceledException(completedTask))
             ctxt.econt edi
         elif completedTask.IsFaulted then
-            let edi = ExceptionDispatchInfo.RestoreOrCapture completedTask.Exception
+            let e =
+                if unwrap then
+                    UnwrapExn completedTask.Exception
+                else
+                    completedTask.Exception
+
+            let edi = ExceptionDispatchInfo.RestoreOrCapture e
             ctxt.econt edi
         else
             ctxt.cont ()
@@ -1246,10 +1266,10 @@ module AsyncPrimitives =
     // completing the task. This will install a new trampoline on that thread and continue the
     // execution of the async there.
     [<DebuggerHidden>]
-    let AttachContinuationToTask (task: Task<'T>) (ctxt: AsyncActivation<'T>) =
+    let AttachContinuationToTask unwrap (task: Task<'T>) (ctxt: AsyncActivation<'T>) =
         task.ContinueWith(
             Action<Task<'T>>(fun completedTask ->
-                ctxt.trampolineHolder.ExecuteWithTrampoline(fun () -> OnTaskCompleted completedTask ctxt)
+                ctxt.trampolineHolder.ExecuteWithTrampoline(fun () -> OnTaskCompleted unwrap completedTask ctxt)
                 |> unfake),
             TaskContinuationOptions.ExecuteSynchronously
         )
@@ -1261,16 +1281,36 @@ module AsyncPrimitives =
     // completing the task. This will install a new trampoline on that thread and continue the
     // execution of the async there.
     [<DebuggerHidden>]
-    let AttachContinuationToUnitTask (task: Task) (ctxt: AsyncActivation<unit>) =
+    let AttachContinuationToUnitTask unwrap (task: Task) (ctxt: AsyncActivation<unit>) =
         task.ContinueWith(
             Action<Task>(fun completedTask ->
-                ctxt.trampolineHolder.ExecuteWithTrampoline(fun () -> OnUnitTaskCompleted completedTask ctxt)
+                ctxt.trampolineHolder.ExecuteWithTrampoline(fun () -> OnUnitTaskCompleted unwrap completedTask ctxt)
                 |> unfake),
             TaskContinuationOptions.ExecuteSynchronously
         )
         |> ignore
         |> fake
 
+    let AwaitTask unwrap (task: Task<'T>) =
+        MakeAsyncWithCancelCheck(fun ctxt ->
+            if task.IsCompleted then
+                // Run synchronously without installing new trampoline
+                OnTaskCompleted unwrap task ctxt
+            else
+                // Continue asynchronously, via syncContext if necessary, installing new trampoline
+                let ctxt = DelimitSyncContext ctxt
+                ctxt.ProtectCode(fun () -> AttachContinuationToTask unwrap task ctxt))
+
+    let AwaitUnitTask unwrap (task: Task) =
+        MakeAsyncWithCancelCheck(fun ctxt ->
+            if task.IsCompleted then
+                // Continue synchronously without installing new trampoline
+                OnUnitTaskCompleted unwrap task ctxt
+            else
+                // Continue asynchronously, via syncContext if necessary, installing new trampoline
+                let ctxt = DelimitSyncContext ctxt
+                ctxt.ProtectCode(fun () -> AttachContinuationToUnitTask unwrap task ctxt))
+
     /// Removes a registration places on a cancellation token
     let DisposeCancellationRegistration (registration: byref<CancellationTokenRegistration option>) =
         match registration with
@@ -2203,24 +2243,30 @@ type Async =
         CreateWhenCancelledAsync compensation computation
 
     static member AwaitTask(task: Task<'T>) : Async<'T> =
-        MakeAsyncWithCancelCheck(fun ctxt ->
-            if task.IsCompleted then
-                // Run synchronously without installing new trampoline
-                OnTaskCompleted task ctxt
-            else
-                // Continue asynchronously, via syncContext if necessary, installing new trampoline
-                let ctxt = DelimitSyncContext ctxt
-                ctxt.ProtectCode(fun () -> AttachContinuationToTask task ctxt))
+        AwaitTask false task
 
     static member AwaitTask(task: Task) : Async<unit> =
-        MakeAsyncWithCancelCheck(fun ctxt ->
-            if task.IsCompleted then
-                // Continue synchronously without installing new trampoline
-                OnUnitTaskCompleted task ctxt
-            else
-                // Continue asynchronously, via syncContext if necessary, installing new trampoline
-                let ctxt = DelimitSyncContext ctxt
-                ctxt.ProtectCode(fun () -> AttachContinuationToUnitTask task ctxt))
+        AwaitUnitTask false task
+
+    static member Await(task: Task<'T>) : Async<'T> =
+        AwaitTask true task
+
+    static member Await(task: Task) : Async<unit> =
+        AwaitUnitTask true task
+
+#if NETSTANDARD2_1
+    static member Await(task: ValueTask<'T>) : Async<'T> =
+        if task.IsCompleted then
+            async { return task.GetAwaiter().GetResult() }
+        else
+            Async.Await(task.AsTask())
+
+    static member Await(task: ValueTask) : Async<unit> =
+        if task.IsCompleted then
+            async { return task.GetAwaiter().GetResult() }
+        else
+            Async.Await(task.AsTask())
+#endif
 
 module CommonExtensions =
 

src/FSharp.Core/async.fsi

@@ -740,15 +740,14 @@ namespace Microsoft.FSharp.Control
         /// <example-tbd></example-tbd>
         static member AwaitIAsyncResult: iar: IAsyncResult * ?millisecondsTimeout:int -> Async<bool>
 
-        /// <summary>Return an asynchronous computation that will wait for the given task to complete and return
+        /// <summary>Creates an asynchronous computation that will wait asynchronously for the given task to complete, returning
         /// its result.</summary>
         ///
         /// <param name="task">The task to await.</param>
         ///
-        /// <remarks>If an exception occurs in the asynchronous computation then an exception is re-raised by this
-        /// function.
+        /// <remarks>If the task yields an exception, then then the full underlying <see cref="T:System.AggregateException"/>  is re-raised by this function.
         ///
-        /// If the task is cancelled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised. Note
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised. Note
         /// that the task may be governed by a different cancellation token to the overall async computation
         /// where the AwaitTask occurs. In practice you should normally start the task with the
         /// cancellation token returned by <c>let! ct = Async.CancellationToken</c>, and catch
@@ -761,15 +760,13 @@ namespace Microsoft.FSharp.Control
         /// <example-tbd></example-tbd>
         static member AwaitTask: task: Task<'T> -> Async<'T>
 
-        /// <summary>Return an asynchronous computation that will wait for the given task to complete and return
-        /// its result.</summary>
+        /// <summary>Creates an asynchronous computation that will wait asynchronously for the given task to complete.</summary>
         ///
         /// <param name="task">The task to await.</param>
         ///
-        /// <remarks>If an exception occurs in the asynchronous computation then an exception is re-raised by this
-        /// function.
+        /// <remarks>If the task yields an exception, then the full underlying <see cref="T:System.AggregateException"/> is re-raised by this function.
         ///
-        /// If the task is cancelled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised. Note
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised. Note
         /// that the task may be governed by a different cancellation token to the overall async computation
         /// where the AwaitTask occurs. In practice you should normally start the task with the
         /// cancellation token returned by <c>let! ct = Async.CancellationToken</c>, and catch
@@ -782,6 +779,74 @@ namespace Microsoft.FSharp.Control
         /// <example-tbd></example-tbd>
         static member AwaitTask: task: Task -> Async<unit>
 
+        /// <summary>Creates an asynchronous computation that will wait for the given task to complete and return
+        /// its result.</summary>
+        ///
+        /// <param name="task">The task to await.</param>
+        ///
+        /// <remarks>Exceptions from the task are surfaced directly, without wrapping in
+        /// <see cref="T:System.AggregateException"/>. An <see cref="T:System.AggregateException"/>
+        /// will only be surfaced where multiple inner exceptions are present.
+        ///
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised.
+        /// </remarks>
+        ///
+        /// <category index="2">Awaiting Results</category>
+        ///
+        /// <example-tbd></example-tbd>
+        static member Await: task: Task<'T> -> Async<'T>
+
+        /// <summary>Creates an asynchronous computation that will wait for the given task to complete.</summary>
+        ///
+        /// <param name="task">The task to await.</param>
+        ///
+        /// <remarks>Exceptions from the task are surfaced directly, without wrapping in
+        /// <see cref="T:System.AggregateException"/>. An <see cref="T:System.AggregateException"/>
+        /// will only be surfaced where multiple inner exceptions are present.
+        ///
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised.
+        /// </remarks>
+        ///
+        /// <category index="2">Awaiting Results</category>
+        ///
+        /// <example-tbd></example-tbd>
+        static member Await: task: Task -> Async<unit>
+
+#if NETSTANDARD2_1
+        /// <summary>Return an asynchronous computation that will wait for the given task to complete and return
+        /// its result.</summary>
+        ///
+        /// <param name="task">The <c>ValueTask</c> to await.</param>
+        ///
+        /// <remarks>Exceptions from the task are surfaced directly, without wrapping in
+        /// <see cref="T:System.AggregateException"/>. An <see cref="T:System.AggregateException"/>
+        /// will only be surfaced where multiple inner exceptions are present.
+        ///
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised.
+        /// </remarks>
+        ///
+        /// <category index="2">Awaiting Results</category>
+        ///
+        /// <example-tbd></example-tbd>
+        static member Await: task: ValueTask<'T> -> Async<'T>
+
+        /// <summary>Return an asynchronous computation that will wait for the given <c>ValueTask</c> to complete.</summary>
+        ///
+        /// <param name="task">The task to await.</param>
+        ///
+        /// <remarks>Exceptions from the task are surfaced directly, without wrapping in
+        /// <see cref="T:System.AggregateException"/>. An <see cref="T:System.AggregateException"/>
+        /// will only be surfaced where multiple inner exceptions are present.
+        ///
+        /// If the task is canceled then <see cref="F:System.Threading.Tasks.TaskCanceledException"/> is raised.
+        /// </remarks>
+        ///
+        /// <category index="2">Awaiting Results</category>
+        ///
+        /// <example-tbd></example-tbd>
+        static member Await: task: ValueTask -> Async<unit>
+#endif
+
         /// <summary>
         ///  Creates an asynchronous computation that will sleep for the given time. This is scheduled
         ///  using a System.Threading.Timer object. The operation will not block operating system threads

tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl

@@ -644,6 +644,8 @@ Microsoft.FSharp.Control.EventModule: Void Add[T,TDel](Microsoft.FSharp.Core.FSh
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Control.FSharpAsync`1[T]] StartChild[T](Microsoft.FSharp.Control.FSharpAsync`1[T], Microsoft.FSharp.Core.FSharpOption`1[System.Int32])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.FSharpChoice`2[T,System.Exception]] Catch[T](Microsoft.FSharp.Control.FSharpAsync`1[T])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.FSharpOption`1[T]] Choice[T](System.Collections.Generic.IEnumerable`1[Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.FSharpOption`1[T]]])
+Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.Unit] Await(System.Threading.Tasks.Task)
+Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.Unit] Await(System.Threading.Tasks.ValueTask)
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.Unit] AwaitTask(System.Threading.Tasks.Task)
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.Unit] Ignore[T](Microsoft.FSharp.Control.FSharpAsync`1[T])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[Microsoft.FSharp.Core.Unit] Sleep(Int32)
@@ -661,6 +663,8 @@ Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T[]
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T[]] Parallel[T](System.Collections.Generic.IEnumerable`1[Microsoft.FSharp.Control.FSharpAsync`1[T]], Microsoft.FSharp.Core.FSharpOption`1[System.Int32])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T[]] Sequential[T](System.Collections.Generic.IEnumerable`1[Microsoft.FSharp.Control.FSharpAsync`1[T]])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] AwaitEvent[TDel,T](Microsoft.FSharp.Control.IEvent`2[TDel,T], Microsoft.FSharp.Core.FSharpOption`1[Microsoft.FSharp.Core.FSharpFunc`2[Microsoft.FSharp.Core.Unit,Microsoft.FSharp.Core.Unit]])
+Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] Await[T](System.Threading.Tasks.Task`1[T])
+Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] Await[T](System.Threading.Tasks.ValueTask`1[T])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] AwaitTask[T](System.Threading.Tasks.Task`1[T])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] FromBeginEnd[TArg1,TArg2,TArg3,T](TArg1, TArg2, TArg3, Microsoft.FSharp.Core.FSharpFunc`2[System.Tuple`5[TArg1,TArg2,TArg3,System.AsyncCallback,System.Object],System.IAsyncResult], Microsoft.FSharp.Core.FSharpFunc`2[System.IAsyncResult,T], Microsoft.FSharp.Core.FSharpOption`1[Microsoft.FSharp.Core.FSharpFunc`2[Microsoft.FSharp.Core.Unit,Microsoft.FSharp.Core.Unit]])
 Microsoft.FSharp.Control.FSharpAsync: Microsoft.FSharp.Control.FSharpAsync`1[T] FromBeginEnd[TArg1,TArg2,T](TArg1, TArg2, Microsoft.FSharp.Core.FSharpFunc`2[System.Tuple`4[TArg1,TArg2,System.AsyncCallback,System.Object],System.IAsyncResult], Microsoft.FSharp.Core.FSharpFunc`2[System.IAsyncResult,T], Microsoft.FSharp.Core.FSharpOption`1[Microsoft.FSharp.Core.FSharpFunc`2[Microsoft.FSharp.Core.Unit,Microsoft.FSharp.Core.Unit]])