Skip to content

Improve synchronous async callback execution - #3313

Merged
martincostello merged 3 commits into
mainfrom
perf/async-valuetask-fast-path
Nov 7, 2026
Merged

martincostello merged 3 commits into
mainfrom
perf/async-valuetask-fast-path

Conversation

Copilot AI commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Pull Request

The issue or feature being addressed

Reduce overhead for asynchronously exposed pipeline callbacks that complete synchronously.

Details on the issue fix or feature implementation

Add a synchronous-completion fast path that avoids async state machines when callbacks return an already-completed ValueTask. Asynchronous callbacks retain the existing await and exception-capture behavior.

BenchmarkDotNet results

Repeat baseline and changed runs, using MediumRun (15 measurement iterations), on the same host and .NET runtime. Allocated: - is BenchmarkDotNet's report for zero measured bytes. The ratio is branch mean / main baseline mean; values below 1.00x indicate faster branch execution.

Environment: BenchmarkDotNet 0.15.8; .NET 10.0.14; Ubuntu 24.04.3 (container); AMD EPYC 9V74 2.60 GHz (1 CPU, 2 logical/2 physical cores); x64 RyuJIT.

Scenario Main Mean Branch Mean Branch / main Main Error Main StdDev Branch Error Branch StdDev Allocated (both)
ExecuteOutcomeAsync (reference) 27.24 ns 30.39 ns 1.12x 0.201 ns 0.288 ns 0.155 ns 0.201 ns -
ExecuteAsync_ResilienceContextAndState 74.70 ns 53.91 ns 0.72x 2.250 ns 3.080 ns 0.363 ns 0.532 ns -
ExecuteAsync_CancellationToken 81.89 ns 50.45 ns 0.62x 2.838 ns 4.071 ns 0.400 ns 0.573 ns -
ExecuteAsync_GenericStrategy_CancellationToken 79.26 ns 53.09 ns 0.67x 0.534 ns 0.749 ns 0.470 ns 0.628 ns -
Execute_ResilienceContextAndState 24.50 ns 23.21 ns 0.95x 0.265 ns 0.363 ns 0.052 ns 0.073 ns -
Execute_CancellationToken 28.18 ns 26.05 ns 0.92x 0.137 ns 0.187 ns 0.240 ns 0.336 ns -
Execute_GenericStrategy_CancellationToken 27.53 ns 26.17 ns 0.95x 0.276 ns 0.368 ns 0.158 ns 0.221 ns -

The three async convenience execution cases improved by about 28%, 38%, and 33%, respectively. All reported scenarios remain allocation-free. The outcome API reference and synchronous controls are included for context; their between-run timings are subject to benchmark noise.

Validation: dotnet build ./src/Polly.Core/Polly.Core.csproj --configuration Release --no-restore succeeded for all target frameworks with 0 warnings and 0 errors. dotnet test ./test/Polly.Core.Tests/Polly.Core.Tests.csproj --configuration Release --no-restore --framework net10.0 passed all 798 tests.

Confirm the following

  • I started this PR by branching from the head of the default branch
  • I have targeted the PR to merge into the default branch
  • I have included unit tests for the issue/feature
  • I have successfully run a local build
  • I have the experience and knowledge necessary to understand, review, and validate all content in this PR.
  • This PR has content that I did not fully write myself.
    • I used AI to assist in writing or reviewing the content of this PR.

Note

This PR description was generated with GitHub Copilot.

Add a fast path for synchronously completed ValueTasks in pipeline execution. Preserve asynchronous exception capture while avoiding state machines for common completed callbacks.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Reorder members.
- Make `CA1031` suppressions more localised.
@codecov

codecov Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.04%. Comparing base (b6df659) to head (41958a5).
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #3313   +/-   ##
=======================================
  Coverage   98.04%   98.04%           
=======================================
  Files         321      321           
  Lines        7148     7157    +9     
  Branches     1105     1107    +2     
=======================================
+ Hits         7008     7017    +9     
  Misses         98       98           
  Partials       42       42           
Flag Coverage Δ
linux 98.03% <100.00%> (+<0.01%) ⬆️
macos 98.03% <100.00%> (+<0.01%) ⬆️
windows 98.04% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@martincostello

Copy link
Copy Markdown
Member

Independent benchmark verification

I re-ran ResiliencePipelineBenchmark locally to verify the numbers in the description, paying particular attention to the apparent 1.12x regression reported for ExecuteOutcomeAsync.

Method: short run (--warmupCount 3 --iterationCount 7 --launchCount 1) of the full benchmark class, three interleaved rounds (branch, baseline, branch, baseline, branch, baseline). The baseline was a separate worktree at the merge base with main (b6df659). The process was pinned to the P-cores with --affinity 4095 to avoid hybrid-core scheduling noise.

Environment: BenchmarkDotNet v0.15.8; .NET 10.0.14; Windows 11 (10.0.26300); 13th Gen Intel Core i7-13700H; X64 RyuJIT x86-64-v3; InProcessEmitToolchain.

Scenario Main mean (ns), rounds 1/2/3 Branch mean (ns), rounds 1/2/3 Branch / main (avg) Allocated (both)
ExecuteOutcomeAsync (reference) 23.8 / 23.1 / 21.4 22.7 / 24.6 / 23.6 1.03x -
ExecuteAsync_ResilienceContextAndState 51.9 / 52.7 / 49.6 34.5 / 35.2 / 34.8 0.68x -
ExecuteAsync_CancellationToken 53.8 / 54.3 / 51.2 37.0 / 41.0 / 36.2 0.72x -
ExecuteAsync_GenericStrategy_CancellationToken 57.1 / 56.3 / 51.8 38.4 / 42.3 / 36.1 0.71x -
Execute_ResilienceContextAndState 27.3 / 25.6 / 24.5 26.5 / 24.2 / 25.5 0.98x -
Execute_CancellationToken 29.2 / 29.0 / 28.5 27.4 / 26.2 / 25.3 0.91x -
Execute_GenericStrategy_CancellationToken 29.7 / 28.5 / 25.4 28.1 / 26.0 / 24.6 0.94x -

Conclusions

  • The three async convenience overloads improve by roughly 28-32% in every round, consistent with the 28/38/33% claimed in the description. The gap is well outside the per-run error (roughly 1-3 ns).
  • The ExecuteOutcomeAsync "regression" does not reproduce. The branch was faster in round 1 and slower in rounds 2 and 3, and the round-to-round spread on a single side is as large as the difference between sides. This is expected: the PR does not modify ExecuteOutcomeAsync or anything it calls, only the ExecuteAsync overloads and the new Outcome.FromValueTask helpers. The 1.12x figure in the description is most likely noise from the 2-core container it was measured on.
  • The synchronous Execute controls are unchanged, as expected.
  • All scenarios remain allocation-free on both sides.

Note

This comment was generated with Claude Code.

Add test coverage for new optimisations.
@martincostello martincostello added this to the v8.9.1 milestone Nov 7, 2026
@martincostello
martincostello marked this pull request as ready for review November 7, 2026 14:54
Copilot AI balanced review requested due to automatic review settings November 7, 2026 14:54
@martincostello
martincostello merged commit ed9c694 into main Nov 7, 2026
29 checks passed
@martincostello
martincostello deleted the perf/async-valuetask-fast-path branch November 7, 2026 14:55

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The successful non-generic fast path skips consuming completed ValueTasks, potentially preventing resource release or pool return across all four non-result ExecuteAsync overloads.

1 open issue
What changed in this PR

This PR reduces callback overhead in Polly.Core async pipeline execution by adding a fast path for synchronously completed ValueTask callbacks.

Changes:

  • Adds internal outcome-conversion helpers with synchronous fast paths and asynchronous exception capture.
  • Routes result-returning and non-result async execution overloads through those helpers.
  • Adds tests for completion, faults, cancellation, and asynchronous exception propagation.
File Description
test/​Polly.Core.Tests/​ResiliencePipelineTests.AsyncT.cs Tests asynchronous result callbacks and exception propagation.
test/​Polly.Core.Tests/​ResiliencePipelineTests.Async.cs Tests asynchronous non-result callbacks and exception propagation.
test/​Polly.Core.Tests/​OutcomeTests.cs Tests outcome conversion for completed, pending, faulted, and canceled tasks.
src/​Polly.Core/​ResiliencePipeline.AsyncT.cs Uses outcome-conversion helpers for result-returning callbacks.
src/​Polly.Core/​ResiliencePipeline.Async.cs Uses outcome-conversion helpers for non-result callbacks.
src/​Polly.Core/​Outcome.cs Adds ValueTask conversion helpers and synchronous fast paths.

Review effort: Balanced

Comment thread src/Polly.Core/Outcome.cs Resolved
This was referenced Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants