feat(Async): RunSynchronouslyImmediate by bartelink · Pull Request #19804 · dotnet/fsharp

bartelink · 2026-05-25T17:55:27Z

Implements RunSynchronouslyImmediate per fsharp/fslang-suggestions#1042

Checklist

Test cases added
- validate absence of thread hops
- contrast with Async.RunSynchronously
xmldoc updated
- mention RSI in RS
- mention RS in RSI
- mention fact SynchronizationContext is not honored in RSI
- mention RS ensures you're on a threadpool thread
- DONT mention RSI does not force you onto a threadpool thread - my assumption is that RS does that for esoteric reasons we don't need to bother users of RSI with?
Release notes entry updated

github-actions · 2026-05-25T17:56:11Z

❗ Release notes required

✅ 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

Copilot

Pull request overview

Adds Async.RunSynchronouslyImmediate to FSharp.Core to allow running an Async<'T> synchronously while always executing the initial step on the calling thread (aimed at improved diagnostics/stack traces in FSI/tests), with accompanying API surface updates, documentation, unit tests, and release notes.

Changes:

Add public API Async.RunSynchronouslyImmediate and wire it through Async primitives.
Add unit tests characterizing basic behavior and key differences vs Async.RunSynchronously.
Update FSharp.Core surface area baselines and release notes; extend XML docs for RunSynchronously/RunSynchronouslyImmediate.

Reviewed changes

Copilot reviewed 8 out of 8 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/AsyncModule.fs	Adds unit tests for `RunSynchronouslyImmediate` and contrasts with `RunSynchronously`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.release.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.release.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.debug.bsl	Records new public surface area entry for `RunSynchronouslyImmediate`.
src/FSharp.Core/async.fsi	Adds XML docs for the new API and revises `RunSynchronously` docs to reference it.
src/FSharp.Core/async.fs	Implements the new API by exposing an “immediate” synchronous runner and refactoring `RunSynchronously` internals.
docs/release-notes/.FSharp.Core/11.0.100.md	Adds release note entry for `Async.RunSynchronouslyImmediate`.

Comments suppressed due to low confidence (1)

tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModule.fs:527

This test uses a raw Thread but doesn’t capture exceptions from the thread body. Any unexpected exception inside the thread (including from Async.RunSynchronously) will be unhandled and may crash the test process rather than reporting a normal xUnit failure. Capture exceptions in the thread and rethrow/assert after Join.

        let t = Thread(fun () ->
            callerThreadId <- Thread.CurrentThread.ManagedThreadId
            async { runSyncThreadId <- Thread.CurrentThread.ManagedThreadId }
            |> Async.RunSynchronously
            async { immThreadId <- Thread.CurrentThread.ManagedThreadId }
            |> Async.RunSynchronouslyImmediate)

T-Gro · 2026-05-26T11:22:05Z

+        /// <summary><p>Runs the asynchronous computation, starting and blocking on the
+        /// calling thread regardless of <see cref="P:System.Threading.SynchronizationContext.Current"/> being non-
+        /// <c>null</c> or <see cref="P:System.Threading.Thread.IsThreadPoolThread"/> being <c>false</c>.</p>
+        /// <p>Any exception raised by the computation is propagated to the caller, with a stack trace bearing
+        /// caller frames for exceptions raised before the first asynchronous suspension.</p>
+        /// <p>Warning: may cause deadlock if called on a UI thread.</p>
+        /// </summary>
        ///
-        /// The timeout parameter is given in milliseconds.  A value of -1 is equivalent to
-        /// <see cref="F:System.Threading.Timeout.Infinite"/>.
+        /// <remarks>
+        /// <p>Warning: this method hard-blocks the calling thread for the duration of the computation,
+        /// including threads that have a non-<c>null</c>
+        /// <see cref="P:System.Threading.SynchronizationContext.Current"/> such as UI threads. Calling it
+        /// from a UI thread will make the UI unresponsive and risks deadlock if any continuation in the
+        /// computation needs to be dispatched back to that context.
+        /// </p>


Summary and remarks feel very much like.

Maybe summary = launches on the calling thread and what it is good for
remarks - the exact conditions and risks

?

@T-Gro see #19804 (comment) - I'll rewrite the xmldoc based on what we decide. I agree that there should be less/no duplication, and summary should mention only risk (deadlock), especially if only key reason to use new fn is to get a direct callstack in a debugger.

Heavily revised now - trying to stick to facts and being terse as the value prop for one vs the other doesn't feel slam dunk to me. Open to concrete suggestions!

(NOTE screenshot of rendered version in OP)

T-Gro · 2026-05-26T11:24:09Z

        /// </code>
-        /// Prints "A", "B" immediately, then "C", "D" in 1 second. result is set to 17.
+        /// Prints <c>"A"</c>, <c>"B"</c> immediately (on the calling thread),
+        /// then (from a continuation thread), after about one second, <c>"C"</c>,


Isn't the example commentary ((from a continuation thread)) swapped between the two versions?

I'll double check after the rewrite when my comment in main thread is resolved - lots of cut and paste going on. Assuming the key diff is deemed to be less noise in the stack trace, the examples will emphasize that the first block prior to suspension runs on calling thread vs a threadpool thread

switched to conveying via EOL comments. Wordings can definitely be improved and/or tightened so open to any suggestions

(NOTE screenshot of rendered version in OP)

bartelink · 2026-05-26T11:28:21Z

@T-Gro I've implemented as per OP of fsharp/fslang-suggestions#1042

Firstly, in a debugger context a first chance exception breakpoint has more direct causation vs having to disentangle an adjacent thread waiting, which tooling may or may not be able to convey unaided.

However, while the exception stack trace has less noise, it's not significantly better AFAICT:

It seems the TL;DR value prop is:

in a debugger breakpoint there's an obvious call stack
stack traces have 2/3 less noise layers
default perf is better as no egregious thread hops (though for many real world cases, there may be a root RunSynchronously that pays the hop price and then nested calls don't pay?)

But its not a slam dunk as:

potential deadlocks
confusion about a longstanding thing that people's fingers and thousands of tutorials had

This is making me think I should dial back the xmldoc from where I have it trying to set a "use the new RunSynchronouslyImmediate in FSI from now on" vibe (as I've tried to do with AwaitTask vs Await where it is a slam dunk)

Final stacktrace comparison:

cc @majocha @dsyme

bartelink · 2026-05-26T11:43:50Z

        |> unfake

+    [<DebuggerHidden>]
+    let RunSynchronouslyImmediate2 computation (cancellationToken: CancellationToken) =


@T-Gro If I put this body (which gives a shorter callstack than the original RunSynchronouslyImmediate impl at L1141) into RunSynchronouslyImmediate, the tests also pass but I guess there is more risk of regressions due to changing a very hot path.

Let me know if you'd prefer for RunSynchronouslyImmediate2 and RunSynchronouslyImmediate to live on side by side as the code is now, or whether you're ok with me collapsing the two into this impl

(applied now - can revert if you think it's a step too far)

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

bartelink · 2026-05-26T22:17:04Z

+    let RunSynchronouslyImmediate<'T> computation (cancellationToken: CancellationToken) =
+        let tcs = TaskCompletionSource<'T>()

-            computation.Invoke ctxt)
-        |> unfake
-
-        let res = resultCell.TryWaitForResultSynchronously().Value
-        res.Commit()
+        StartWithContinuations
+            cancellationToken
+            computation
+            tcs.SetResult
+            (fun edi -> tcs.SetException edi.SourceException)
+            (fun _ -> tcs.SetCanceled())
+        // Synchronously block waiting for the result (i.e. even if continuations run on another thread, this caller will busy-wait)
+        tcs.Task.GetAwaiter().GetResult() // GetResult() unpacks the AggregateException that .Result would present

    [<DebuggerHidden>]
-    let RunSynchronously cancellationToken (computation: Async<'T>) timeout =
-        // Reuse the current ThreadPool thread if possible.
+    let RunSynchronouslyBackgroundThreadPool (computation: Async<'T>) cancellationToken timeout =
+        // Run inline only where it's guaranteed to be safe
        match SynchronizationContext.Current, Thread.CurrentThread.IsThreadPoolThread, timeout with
-        | null, true, None -> RunImmediate cancellationToken computation
-        | _ -> QueueAsyncAndWaitForResultSynchronously cancellationToken computation timeout
+        | null, true, None -> RunSynchronouslyImmediate computation cancellationToken // best stacktrace in case of exception


@T-Gro this is the key implication of settling on a uniform simplified impl of RunSynchronouslyImmediate shared between it and [the no-thread-hop path of] RunSynchronously

IMO If we roll it back, we get messier stack traces and uglier code so I'm suggesting we take this inconsistency hit.

bartelink · 2026-05-26T22:22:15Z

    /// Run the asynchronous workflow and wait for its result.
    [<DebuggerHidden>]
-    let QueueAsyncAndWaitForResultSynchronously (token: CancellationToken) computation timeout =
+    let QueueAsyncAndWaitForResultSynchronously computation (token: CancellationToken) timeout =


can revert this, but trying to get arg order consistent across most involved functions

bartelink · 2026-05-26T22:22:52Z

-                    trampolineHolder
-                    (fun res -> resultCell.RegisterResult(AsyncResult.Ok res, reuseThread = true))
-                    (fun edi -> resultCell.RegisterResult(AsyncResult.Error edi, reuseThread = true))
-                    (fun exn -> resultCell.RegisterResult(AsyncResult.Canceled exn, reuseThread = true))


old behavior resulting in OperationCanceledException

bartelink · 2026-05-26T22:25:37Z

            computation
        |> unfake

-    [<DebuggerHidden>]


moved up as required by RunSynchronously

note the whole PR could be made much shorter by having the Async layer call Async.FromContinuations

However, as mentioned in other places, I believe its for the best that RunSynchronouslyImmediate and the immediate path of RunSychronously should have strong clear ties in the lower layer as this PR does

bartelink · 2026-05-26T22:27:28Z

+        Assert.NotEqual(callerThreadId, runSyncThreadId)
+        Assert.Equal(callerThreadId, immThreadId)
+
+    [<Fact>]


I'm not particularly attached to this test, and it can be argued that it's a red herring/aside/distraction

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

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

feat(Async): RunSynchronouslyImmediate

41f5f13

bartelink force-pushed the run-synchronously-immediate branch from 181ce94 to 41f5f13 Compare May 25, 2026 18:44

Doc polish / characterization tests

69e41a2

bartelink force-pushed the run-synchronously-immediate branch from d6a0470 to 69e41a2 Compare May 25, 2026 22:07

bartelink marked this pull request as ready for review May 25, 2026 22:19

bartelink requested a review from a team as a code owner May 25, 2026 22:19

Copilot AI review requested due to automatic review settings May 25, 2026 22:19

Copilot started reviewing on behalf of bartelink May 25, 2026 22:19 View session

Copilot AI reviewed May 25, 2026

View reviewed changes

Comment thread tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModule.fs Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

Comment thread src/FSharp.Core/async.fsi Outdated

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

bartelink added 2 commits May 26, 2026 11:03

copilot Code review changes

19e3482

RunSynchronouslyImmediate2

cc7fe0b

T-Gro reviewed May 26, 2026

View reviewed changes

bartelink mentioned this pull request May 26, 2026

Add Async.RunImmediate fsharp/fslang-suggestions#1042

Open

5 tasks

bartelink commented May 26, 2026

View reviewed changes

bartelink added 2 commits May 26, 2026 16:25

Remove duplication

173a0ed

diff reduction

f9e0383

bartelink force-pushed the run-synchronously-immediate branch from 75fed30 to f9e0383 Compare May 26, 2026 15:40

bartelink commented May 26, 2026

View reviewed changes

heavily revise xmldoc

d6ca6e0

bartelink requested review from T-Gro and Copilot May 26, 2026 21:31

Copilot AI reviewed May 26, 2026

View reviewed changes

Address copilot review

013acc1

bartelink commented May 26, 2026

View reviewed changes

Conversation

bartelink commented May 25, 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 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❗ 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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink May 26, 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 May 26, 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!

bartelink May 26, 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!

bartelink commented May 26, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartelink May 26, 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bartelink commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading

bartelink May 26, 2026 •

edited

Loading

bartelink May 26, 2026 •

edited

Loading

bartelink May 26, 2026 •

edited

Loading

bartelink commented May 26, 2026 •

edited

Loading

bartelink May 26, 2026 •

edited

Loading