From 0cebeea2cdae10490a5c944600a0af0de4b74f6f Mon Sep 17 00:00:00 2001
From: martintmk <103487740+martintmk@users.noreply.github.com>
Date: Tue, 25 Jul 2023 11:41:20 +0200
Subject: [PATCH] Improve usability of ResilienceStrategy<T> (#1428)

---
 src/Polly.Core/PublicAPI.Unshipped.txt        | 24 ++++++++---------
 .../ResilienceStrategy.TResult.Async.cs       | 25 ++++++++++++------
 .../ResilienceStrategy.TResult.Sync.cs        | 26 ++++++++++++++-----
 3 files changed, 48 insertions(+), 27 deletions(-)

diff --git a/src/Polly.Core/PublicAPI.Unshipped.txt b/src/Polly.Core/PublicAPI.Unshipped.txt
index 87c39641991..29884cc11e7 100644
--- a/src/Polly.Core/PublicAPI.Unshipped.txt
+++ b/src/Polly.Core/PublicAPI.Unshipped.txt
@@ -248,18 +248,18 @@ Polly.ResilienceStrategy.ExecuteAsync<TState>(System.Func<Polly.ResilienceContex
 Polly.ResilienceStrategy.ExecuteAsync<TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask
 Polly.ResilienceStrategy.ExecuteOutcomeAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
 Polly.ResilienceStrategy.ResilienceStrategy() -> void
-Polly.ResilienceStrategy<TResult>
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<Polly.ResilienceContext!, TResult>! callback, Polly.ResilienceContext! context) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<System.Threading.CancellationToken, TResult>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute(System.Func<TResult>! callback) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<Polly.ResilienceContext!, TState, TResult>! callback, Polly.ResilienceContext! context, TState state) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<TState, System.Threading.CancellationToken, TResult>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
-Polly.ResilienceStrategy<TResult>.Execute<TState>(System.Func<TState, TResult>! callback, TState state) -> TResult
-Polly.ResilienceStrategy<TResult>.ExecuteAsync(System.Func<Polly.ResilienceContext!, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync(System.Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync<TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteAsync<TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
-Polly.ResilienceStrategy<TResult>.ExecuteOutcomeAsync<TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
+Polly.ResilienceStrategy<T>
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, TResult>! callback, Polly.ResilienceContext! context, TState state) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<TState, System.Threading.CancellationToken, TResult>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult, TState>(System.Func<TState, TResult>! callback, TState state) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<Polly.ResilienceContext!, TResult>! callback, Polly.ResilienceContext! context) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<System.Threading.CancellationToken, TResult>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> TResult
+Polly.ResilienceStrategy<T>.Execute<TResult>(System.Func<TResult>! callback) -> TResult
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult, TState>(System.Func<TState, System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, TState state, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult>(System.Func<Polly.ResilienceContext!, System.Threading.Tasks.ValueTask<TResult>>! callback, Polly.ResilienceContext! context) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteAsync<TResult>(System.Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<TResult>>! callback, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
+Polly.ResilienceStrategy<T>.ExecuteOutcomeAsync<TResult, TState>(System.Func<Polly.ResilienceContext!, TState, System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>>! callback, Polly.ResilienceContext! context, TState state) -> System.Threading.Tasks.ValueTask<Polly.Outcome<TResult>>
 Polly.ResilienceStrategyBuilder
 Polly.ResilienceStrategyBuilder.Build() -> Polly.ResilienceStrategy!
 Polly.ResilienceStrategyBuilder.ResilienceStrategyBuilder() -> void
diff --git a/src/Polly.Core/ResilienceStrategy.TResult.Async.cs b/src/Polly.Core/ResilienceStrategy.TResult.Async.cs
index da8df1b7f69..c5c9752a759 100644
--- a/src/Polly.Core/ResilienceStrategy.TResult.Async.cs
+++ b/src/Polly.Core/ResilienceStrategy.TResult.Async.cs
@@ -7,12 +7,12 @@ namespace Polly;
 /// <summary>
 /// Resilience strategy is used to execute the user-provided callbacks.
 /// </summary>
-/// <typeparam name="TResult">The type of result this strategy supports.</typeparam>
+/// <typeparam name="T">The type of result this strategy supports.</typeparam>
 /// <remarks>
-/// Resilience strategy supports various types of callbacks of <typeparamref name="TResult"/> result type
+/// Resilience strategy supports various types of callbacks of <typeparamref name="T"/> result type
 /// and provides a unified way to execute them. This includes overloads for synchronous and asynchronous callbacks.
 /// </remarks>
-public partial class ResilienceStrategy<TResult>
+public partial class ResilienceStrategy<T>
 {
     internal ResilienceStrategy(ResilienceStrategy strategy) => Strategy = strategy;
 
@@ -21,16 +21,18 @@ public partial class ResilienceStrategy<TResult>
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync<TState>(
+    public ValueTask<TResult> ExecuteAsync<TResult, TState>(
         Func<ResilienceContext, TState, ValueTask<TResult>> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -41,13 +43,15 @@ public ValueTask<TResult> ExecuteAsync<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync(
+    public ValueTask<TResult> ExecuteAsync<TResult>(
         Func<ResilienceContext, ValueTask<TResult>> callback,
         ResilienceContext context)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -58,16 +62,18 @@ public ValueTask<TResult> ExecuteAsync(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync<TState>(
+    public ValueTask<TResult> ExecuteAsync<TResult, TState>(
         Func<TState, CancellationToken, ValueTask<TResult>> callback,
         TState state,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -77,11 +83,12 @@ public ValueTask<TResult> ExecuteAsync<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>The instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public ValueTask<TResult> ExecuteAsync(
+    public ValueTask<TResult> ExecuteAsync<TResult>(
         Func<CancellationToken, ValueTask<TResult>> callback,
         CancellationToken cancellationToken = default)
     {
@@ -93,6 +100,7 @@ public ValueTask<TResult> ExecuteAsync(
     /// <summary>
     /// Executes the specified outcome-based callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
@@ -103,10 +111,11 @@ public ValueTask<TResult> ExecuteAsync(
     /// This method is for advanced and high performance scenarios. The caller must make sure that the <paramref name="callback"/>
     /// does not throw any exceptions. Instead, it converts them to <see cref="Outcome{TResult}"/>.
     /// </remarks>
-    public ValueTask<Outcome<TResult>> ExecuteOutcomeAsync<TState>(
+    public ValueTask<Outcome<TResult>> ExecuteOutcomeAsync<TResult, TState>(
         Func<ResilienceContext, TState, ValueTask<Outcome<TResult>>> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
diff --git a/src/Polly.Core/ResilienceStrategy.TResult.Sync.cs b/src/Polly.Core/ResilienceStrategy.TResult.Sync.cs
index 65149ee2c48..b21034af0e0 100644
--- a/src/Polly.Core/ResilienceStrategy.TResult.Sync.cs
+++ b/src/Polly.Core/ResilienceStrategy.TResult.Sync.cs
@@ -2,21 +2,23 @@ namespace Polly;
 
 #pragma warning disable RS0027 // API with optional parameter(s) should have the most parameters amongst its public overloads
 
-public partial class ResilienceStrategy<TResult>
+public partial class ResilienceStrategy<T>
 {
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(
+    public TResult Execute<TResult, TState>(
         Func<ResilienceContext, TState, TResult> callback,
         ResilienceContext context,
         TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -27,13 +29,15 @@ public TResult Execute<TState>(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="context">The context associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> or <paramref name="context"/> is <see langword="null"/>.</exception>
-    public TResult Execute(
+    public TResult Execute<TResult>(
         Func<ResilienceContext, TResult> callback,
         ResilienceContext context)
+        where TResult : T
     {
         Guard.NotNull(callback);
         Guard.NotNull(context);
@@ -44,13 +48,15 @@ public TResult Execute(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute(
+    public TResult Execute<TResult>(
         Func<CancellationToken, TResult> callback,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -60,10 +66,12 @@ public TResult Execute(
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute(Func<TResult> callback)
+    public TResult Execute<TResult>(Func<TResult> callback)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -73,12 +81,14 @@ public TResult Execute(Func<TResult> callback)
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(Func<TState, TResult> callback, TState state)
+    public TResult Execute<TResult, TState>(Func<TState, TResult> callback, TState state)
+        where TResult : T
     {
         Guard.NotNull(callback);
 
@@ -88,16 +98,18 @@ public TResult Execute<TState>(Func<TState, TResult> callback, TState state)
     /// <summary>
     /// Executes the specified callback.
     /// </summary>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
     /// <typeparam name="TState">The type of state associated with the callback.</typeparam>
     /// <param name="callback">The user-provided callback.</param>
     /// <param name="state">The state associated with the callback.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> associated with the callback.</param>
     /// <returns>An instance of <see cref="ValueTask"/> that represents the asynchronous execution.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="callback"/> is <see langword="null"/>.</exception>
-    public TResult Execute<TState>(
+    public TResult Execute<TResult, TState>(
         Func<TState, CancellationToken, TResult> callback,
         TState state,
         CancellationToken cancellationToken = default)
+        where TResult : T
     {
         Guard.NotNull(callback);