Skip to content

Commit

Permalink
Improve usability of ResilienceStrategy<T> (#1428)
Browse files Browse the repository at this point in the history
  • Loading branch information
@martintmk
martintmk authored Jul 25, 2023
1 parent 59e461a commit 0cebeea
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 27 deletions.
24 changes: 12 additions & 12 deletions src/Polly.Core/PublicAPI.Unshipped.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 17 additions & 8 deletions src/Polly.Core/ResilienceStrategy.TResult.Async.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);

Expand All @@ -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)
{
Expand All @@ -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>
Expand All @@ -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);
Expand Down
26 changes: 19 additions & 7 deletions src/Polly.Core/ResilienceStrategy.TResult.Sync.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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);

Expand All @@ -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);

Expand All @@ -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);

Expand All @@ -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);

Expand Down

0 comments on commit 0cebeea

Please sign in to comment.