feat(Async+Task+ValueTask): consistent helper modules by bartelink · Pull Request #19844 · dotnet/fsharp

bartelink · 2026-05-28T10:43:47Z

Adds consistent helper modules for Async, Task and ValueTask.

Resolves fsharp/fslang-suggestions#1466

Checklist

Test cases added
Release notes entry updated
await conclusions on whether to include debatable ones
~~consider a Task.wait helper~~ not now anyway

github-actions · 2026-05-28T10:44:26Z

✅ No release notes required

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds new camelCase helpers for Async, Task, and ValueTask in FSharp.Core, along with unit tests and surface area/release note updates.

Changes:

Introduced result, map, bind, ignore, catchWith, catch, empty for Async, Task, ValueTask (+ Task.ofValueTask, ValueTask.ofTask where available).
Added unit tests covering success/failure flows for the new helpers.
Updated netstandard surface area baselines and release notes.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/TaskModuleFunctions.fs	New tests for `Task`/`ValueTask` camelCase helpers.
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModuleFunctions.fs	New tests for `Async` camelCase helpers.
tests/FSharp.Core.UnitTests/FSharp.Core.UnitTests.fsproj	Includes the new test files in the test project.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.release.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.release.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.debug.bsl	Surface area baseline updated for new APIs.
src/FSharp.Core/tasks.fsi	Public signatures/docs for new `Task`/`ValueTask` modules.
src/FSharp.Core/tasks.fs	Implementation of new `Task`/`ValueTask` helpers.
src/FSharp.Core/async.fsi	Public signatures/docs for new `Async` camelCase helpers.
src/FSharp.Core/async.fs	Implementation of new `Async` camelCase helpers.
docs/release-notes/.FSharp.Core/11.0.100.md	Release notes entry for the new APIs.

T-Gro · 2026-07-11T09:08:51Z

+
+### Added
+
+* Added camelCase module-level functions `result`, `map`, `bind`, `ignore`, `catchWith`, `catch`, and `empty` in `module`s `Async`,`Task` and `ValueTask`, plus `Task.ofValueTask` and `ValueTask.ofTask`. ([LanguageSuggestion #1466](https://github.com/fsharp/fslang-suggestions/issues/1466), [PR #19844](https://github.com/dotnet/fsharp/pull/19844))


Still open: `module`s → modules, plus comma-space → modules Async, Task, ValueTask``.

reworded in 6708b8f to make format more consistent if there's any other functions added any time soon.

T-Gro · 2026-06-12T10:27:56Z

@bartelink :

Hi Ruben, just to let you know - I am waiting for when we stop flowing into .NET 10 releases (10.0.400).
Once we branch off to do NET11 only from main, I will have another look (but looks ready) at all your PRs and merge if no objections 👍 .

bartelink · 2026-06-12T11:09:35Z

Thanks @T-Gro; will be ready when the times come.

Some open questions for when you have a minute to scan:

Any thoughts on whether other more fringe things can/should make it in e.g. Task.parallelLimit feat(Task, Async): parallelLimit, parallelDoLimit bartelink/fsharp#2 - if the answer is >= maybe then we should discuss things like e.g. extending the base impl to e.g. avoid generating any redundant Task instances and/or canceling in flight work once an exception is raised (there doesn't seem to be any easy/solid BCL idiomatic ways to accomplish this beyond that simple impl AFAICT)
Wondering if you see the value/point in including a [Task|Async|ValueTask].wait/runSync Add Async.RunImmediate fsharp/fslang-suggestions#1042 (comment) function - probably confirmation bias, but I keep seeing places this would clean things up ever since I wrote that (will rely on Async.Await)
ICYMI I have a StartTaskImmediate stacked in the wings, awaiting Async.Await feat(Async): StartTaskImmediate bartelink/fsharp#1

bartelink · 2026-06-30T10:33:42Z

@T-Gro Two more notes

The Async+Task.wait I proposed/mused about also addresses the ask for a syncTask or similar for top level and/or interactive task running
you added a 👍 on my tangential comment re pickV and friends but on closer inspection a module ValueOption is already in place and pretty complete. Can you clarify here which aspect, if any of my proposals you felt merited expansion into a suggestion and/or considering doing please?

T-Gro

Focused on the consistency premise across Async/Task/ValueTask. Two decisions already settled: module suffix (compiled TaskModule/ValueTaskModule) and cancellation propagates everywhere (first-class, not caught like a normal exception — applies to both catch and catchWith). Inline comments have repros + proposed fixes.

T-Gro · 2026-07-11T07:12:47Z

+                    return handler e
+            }
+
+    [<CompiledName("Catch")>]


catch demotes cancellation to Error — also ValueTask.catch (:860). Reverses the shipped Error(cancelled) test; decision is to treat cancellation as first-class, consistent with Async.

Task.FromCanceled<int>(CancellationToken true) |> Task.catch

result is Error (TaskCanceledException)

Async.catch propagates; Error should be reserved for genuine faults

Proposed fix:

TaskBuilder.task { try let! v = task return Ok v with | :? OperationCanceledException as e -> return raise e // stays Canceled | e -> return Error e }

(corrected; pushed for Task, but not yet for ValueTask)
Thanks for the catch, the proposed fix works (though I wonder if the stack trace is optimal and/or whether that's the canonical way to bail on cancellation)

@T-Gro I guess map, bind, catch, catchWith should each have xmldoc covering the pinned behavior? i.e. I'm thinking that it should allude to the fact that catch will let a TaskCanceledException escape so it's not 100% 1:1 equivalent to task { try let! r = task in Ok r with e -> Error e }

T-Gro · 2026-07-11T07:12:47Z

+    [<CompiledName("Map")>]
+    let inline map ([<InlineIfLambda>] mapping: 'T -> 'U) (task: Task<'T>) : Task<'U> =
+        if task.Status = TaskStatus.RanToCompletion then
+            result (mapping task.Result)


map/bind throw synchronously on already-completed input — also bind (:751) and the ValueTask equivalents (:809/:822).

let boom (_: int) : int = failwith "boom" tcs.Task |> Task.map boom // pending Task.result 21 |> Task.map boom // completed

pending input → faulted Task

completed input → raises at the call site, no Task returned

same call, exception delivered two different ways depending on timing

Proposed fix:

if task.Status = TaskStatus.RanToCompletion then try result (mapping task.Result) with e -> Task.FromException<'U> e

@T-Gro I get the point/concern on the catch variants - easy to test etc and will fix.

same call, exception delivered two different ways depending on timing

But can you clarify the exact desire re cancellation handling please?

This code will use the task { leg in the canceled or faulted case and passes my tests:

if task.Status = TaskStatus.RanToCompletion then result (mapping task.Result) else task { let! v = task return mapping v }

Recall task.Status = TaskStatus.RanToCompletion is a ns2.0 compatible equivalent of .IsCompletedSuccessfully, so AIUI there can't be a throw from that leg, so the proposed fix would never hit its catch?

Changing Status = TaskStatus.RanToCompletion fast path check to to instead use IsCompleted to force a given handling would entail switching to:

if task.IsCompleted then // includes Canceled or Faulted states try result (task.GetAwaiter().GetResult() |> mapping) // Result would surface AggregateException with e -> Task.FromException<'U>(e) else TaskBuilder.task { let! v = task return mapping v }

Current (passing with above impls) test semantics:

[<Fact>] let ``Task.map flows Cancellation (sync)`` () = use cts = new CancellationTokenSource() cts.Cancel() let t = Task.FromCanceled<int>(cts.Token) |> Task.map (fun x -> x * 2) task { let! e = Assert.ThrowsAsync<TaskCanceledException>(fun () -> t) Assert.Equal(cts.Token, e.CancellationToken) } [<Fact>] let ``Task.map flows Cancellation (async)`` () = let tcs = TaskCompletionSource<int>() let t = tcs.Task |> Task.map (fun x -> x * 2) use cts = new CancellationTokenSource() tcs.SetCanceled cts.Token task { let! e = Assert.ThrowsAsync<TaskCanceledException>(fun () -> t) Assert.Equal(cts.Token, e.CancellationToken) } [<Fact>] let ``Task.map propagates exception (sync)`` () = let t = Task.FromException<int>(Exception "boom") |> Task.map (fun x -> x * 2) task { let! e = Assert.ThrowsAnyAsync<exn>(fun () -> t) Assert.Equal("boom", e.Message) } [<Fact>] let ``Task.map propagates exception (async)`` () = let tcs = TaskCompletionSource<int>() let t = tcs.Task |> Task.map (fun x -> x * 2) tcs.SetException(exn "boom") task { let! e = Assert.ThrowsAnyAsync<exn>(fun () -> t) Assert.Equal("boom", e.Message) }

How would one specify/validate the precise semantics you seek? Is it about being able to set a breakpoint?

Anything worth borrowing from prior art?:

https://github.com/fsprojects/FSharpPlus/blob/master/src/FSharpPlus/Extensions/Task.fs#L15-L28
https://github.com/fsprojects/FSharpPlus/blob/master/src/FSharpPlus/Extensions/Task.fs#L85-L96
https://github.com/demystifyfp/FsToolkit.ErrorHandling/blob/master/src/FsToolkit.ErrorHandling/Task.fs#L8-L36

cc @TheAngryByrd @gusty If either of you have time to throw a set of eyes over the impl and the test suite to see if there are any gaps that FsToolkit and/or FSharpPlus cover which should be considered?

https://github.com/bartelink/fsharp/blob/atvt/src/FSharp.Core/tasks.fs#L729-L804
https://github.com/bartelink/fsharp/blob/atvt/tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/TaskModuleFunctions.fs#L11-L274

The aim is for a balance of:

idiomatic / terse impl (optimization can come later (though each function has a sync/completed fast path)

thorough test suite that provides coverage of all intended behaviors, no matter how esoteric (i.e. if this provides bad stack traces and/or usage of return raise e throws away stack traces and the test suite should call that out, I'm interested!

Bottom line it would be good to rule out footguns like egregious AggregateException wrapping or catch/catchWith trapping cancellation from the off

@T-Gro Task test suite reviewed, expanded and polished
catch/catchWith Cancellation handling is corrected

NOTE ValueTask impl and tests are still unchanged - I'll port those when we're happy with Task.

T-Gro · 2026-07-11T07:12:47Z

+
+    [<Fact>]
+    let ``ValueTask.map transforms value (async)`` () =
+        let vt = ValueTask<int>(Task.FromResult 21) |> ValueTask.map (fun x -> x * 2)


"(async)" tests run the sync path — also bind (:203).

ValueTask<int>(Task.FromResult 21).IsCompletedSuccessfully // true

input already completed → fast path; the slow (Task-allocating) branch is untested

also why the map/bind timing issue has no failing test

Proposed fix:

let tcs = TaskCompletionSource<int>() let vt = ValueTask<int>(tcs.Task) |> ValueTask.map (fun x -> x * 2) Assert.False vt.IsCompletedSuccessfully tcs.SetResult 21 Assert.Equal(42, vt.Result)

Apologies for the lack of quality control - will review the suite and make Task vs ValueTask more consistent before forcing it on human eyes again ☹️
(ignore has the same issue, IsCompletedSuccessfully should be IsCompleted etc etc)

(corrected; pushed for Task, but not yet for ValueTask)

T-Gro · 2026-07-11T07:12:47Z

+        /// let readFile filename numBytes =
+        ///     async {
+        ///         use file = System.IO.File.OpenRead(filename)
+        ///         do! file.AsyncRead(numBytes) |> Async.ignore&lt;int&gt;


Doc example doesn't type-check.

file.AsyncRead(numBytes) |> Async.ignore<int>

AsyncRead : int -> Async<byte[]>, so ignore<int> → FS0001

Proposed fix:

file.AsyncRead(numBytes) |> Async.ignore<byte array>

fixed (but using byte[])

T-Gro · 2026-07-11T09:09:08Z

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

Any thoughts on whether other more fringe things can/should make it in e.g. Task.parallelLimit … extending the base impl to avoid redundant Task instances and/or canceling in-flight work once an exception is raised

Let's keep it out of this PR. It adds throttling + cancel-on-first-exception + aggregation and overlaps Parallel.ForEachAsync. The cancel-in-flight story (no clean BCL-idiomatic path, as you note) is exactly why it deserves its own treatment.

Wondering if you see the value/point in including a [Task|Async|ValueTask].wait/runSync … also addresses the ask for a syncTask … (#1459)

The ergonomics are real, but a blessed runSync/wait is a policy call (sync-over-async, deadlock footguns) that these pure combinators don't carry. Let's not fold it in here.

ICYMI I have a StartTaskImmediate stacked in the wings, awaiting Async.Await

Noted — happy to review once that lands.

I believe that clears everything I had outstanding — if I've missed a question anywhere in the thread, or any of the above needs more detail, flag it and I'll follow up.

bartelink · 2026-07-14T15:03:16Z

Thanks for catches - this is ready for re-review from my perspective

Checklist:

port final Task impl and test suite to ValueTask
xmldoc re Cancellation semantics for map, bind, catch, catchWith ?
any follow-ups from @TheAngryByrd @gusty
followups from anyone else - please feel free to refer anyone with relevant expertise (and time!) by atting them in...
remove empty ?

gusty · 2026-07-14T19:12:13Z

+
+    [<CompiledName("Ignore")>]
+    [<RequiresExplicitTypeArguments>]
+    let inline ignore<'T> (task: Task<'T>) : Task<unit> =


Suggested change

let inline ignore<'T> (task: Task<'T>) : Task<unit> =

let inline ignore (task: Task) : Task<unit> =

ignore doesn't accept Task (non generic).

The implementation in F#+ allows to convert a Task to a Task<unit> and I would say in 50% of the scenarios is used in this way. I think we already discussed this.

Hm problem is that people want RequiresExplicitTypeArguments [and hence generic] here
also it has to be a module so no overloading
Would not want to do a one-off ugly name unless there are other cases...
Maybe naming it Task.ofTask (as the inital proposal suggested) would work
But I'm also betting that in the kind of codebase requiring heavy TPL interop this would be only the start of the conversion helpers that would be useful but deep in the long tail in terms of usage count?

(Best discussed in fslang-sugggestion)

gusty · 2026-07-14T19:18:31Z

+            }
+
+    [<CompiledName("Catch")>]
+    let catch (task: Task<'T>) : Task<Result<'T, exn>> =


I think we kind of agreed that this function shouldn't be included for the reasons mentioned in the discussion.

I'm not pretending to restart the discussions, but just looking at the votes. There are 3 "really don't want" against 1 "really want", plus 2 "I'm ok with it", there are more against that in favor.

empty was more lukewarm and I'd venture higher priority to debate...
As my vote indicates, I'd personally prefer it not to be there, but there are people who think it's an important thing to have in the box... The place to debate this this is probably out in the fslang-suggestion though

gusty · 2026-07-14T19:19:12Z

+
+    [<CompiledName("Ignore")>]
+    [<RequiresExplicitTypeArguments>]
+    let inline ignore<'T> (task: ValueTask<'T>) : ValueTask<unit> =


Same comment as for the Task version

github-project-automation Bot added this to F# Compiler and Tooling May 28, 2026

github-project-automation Bot moved this to New in F# Compiler and Tooling May 28, 2026

bartelink force-pushed the atvt branch 2 times, most recently from 5850539 to 7ad7946 Compare May 28, 2026 14:34

bartelink mentioned this pull request May 28, 2026

Add Async.RunImmediate fsharp/fslang-suggestions#1042

Open

5 tasks

bartelink force-pushed the atvt branch from 7ad7946 to 1f5e33f Compare May 28, 2026 15:25

bartelink marked this pull request as ready for review May 28, 2026 15:25

bartelink requested a review from a team as a code owner May 28, 2026 15:25

Copilot AI review requested due to automatic review settings May 28, 2026 15:25

Copilot AI reviewed May 28, 2026

View reviewed changes

bartelink commented May 28, 2026

View reviewed changes

Comment thread src/FSharp.Core/async.fs

github-actions Bot added the AI-Tooling-Check-Scanned-Clean Tooling check: diff analyzed, no interesting infrastructure files label May 28, 2026

bartelink force-pushed the atvt branch from 29b18c1 to 2f5acf6 Compare May 28, 2026 19:30

bartelink added 3 commits June 6, 2026 08:39

feat(Async+Task+ValueTask): consistent helper modules

a21b6c9

copilot review fixes

d2e4b46

Fix netstandard2.0 build

bc83170

bartelink force-pushed the atvt branch from 2f5acf6 to bc83170 Compare June 6, 2026 07:39

T-Gro reviewed Jul 11, 2026

View reviewed changes

bartelink added 5 commits July 13, 2026 18:19

Merge remote-tracking branch 'upstream/main' into atvt

40245a2

docs: reword release notes

6708b8f

fix: Correct doc examples

bb57111

fix(Task, ValueTask): Add ModuleSuffix

60f399e

fix(Task): Complete test suite, correct Cancellation mishandling

cfec168

bartelink force-pushed the atvt branch from a67cc2e to 0b4f225 Compare July 14, 2026 18:05

fix: Test cancelation on ns2.0

ac1ad45

bartelink force-pushed the atvt branch from 0b4f225 to ac1ad45 Compare July 14, 2026 18:06

gusty reviewed Jul 14, 2026

View reviewed changes


		### Added

		* Added camelCase module-level functions `result`, `map`, `bind`, `ignore`, `catchWith`, `catch`, and `empty` in `module`s `Async`,`Task` and `ValueTask`, plus `Task.ofValueTask` and `ValueTask.ofTask`. ([LanguageSuggestion #1466](https://github.com/fsharp/fslang-suggestions/issues/1466), [PR #19844](https://github.com/dotnet/fsharp/pull/19844))

	let inline ignore<'T> (task: Task<'T>) : Task<unit> =
	let inline ignore (task: Task) : Task<unit> =

Uh oh!

Conversation

bartelink commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

github-actions Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ No release notes required

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink Jul 13, 2026 • 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!

Uh oh!

T-Gro commented Jun 12, 2026

Uh oh!

bartelink commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bartelink commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

T-Gro left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink Jul 14, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink Jul 13, 2026 • 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!

T-Gro commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bartelink commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink Jul 14, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

bartelink Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

bartelink commented May 28, 2026 •

edited

Loading

github-actions Bot commented May 28, 2026 •

edited

Loading

bartelink Jul 13, 2026 •

edited

Loading

bartelink commented Jun 12, 2026 •

edited

Loading

bartelink commented Jun 30, 2026 •

edited

Loading

bartelink Jul 14, 2026 •

edited

Loading

bartelink Jul 13, 2026 •

edited

Loading

T-Gro commented Jul 11, 2026 •

edited

Loading

bartelink commented Jul 14, 2026 •

edited

Loading

bartelink Jul 14, 2026 •

edited

Loading

bartelink Jul 14, 2026 •

edited

Loading