feat(Async): RunSynchronouslyImmediate

[bartelink]

Implements RunSynchronouslyImmediate per fsharp/fslang-suggestions#1042

See also fsharp/fslang-suggestions#1467

NOTE the tests (and especially the comments within them) are mainly generated. Similarly the xmldoc updates are a best effort mix of generated content combined with me attempting to increase chances that an intellisense reader will come to the right conclusions in terms of tradeoff between potential deadlock vs better stacktraces. As such, please feel free to relentlessly criticize and/or rewrite to your hearts content.

Checklist

• Needs a killer example of the stacktrace difference between Async.RS vs Async.RSI
  • One aspect should potentially be represented as a regression test
  • More importantly, if the xmldoc summary can shout out the difference / why one should consider deadlocking, that's key
• Test cases added
  • validate absence of thread hops
  • characterize stacktrace that can be expected (perhaps contrasting with RunSynchronously)
• Release notes entry updated:

[ghost]

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

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]

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