API Review Feedback

src/Polly.Core/CircuitBreaker/CircuitBreakerPredicateArguments.cs

@@ -23,12 +23,12 @@ public CircuitBreakerPredicateArguments(ResilienceContext context, Outcome<TResu
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome of user-callback.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 }

src/Polly.Core/CircuitBreaker/OnCircuitClosedArguments.cs

@@ -25,12 +25,12 @@ public OnCircuitClosedArguments(ResilienceContext context, Outcome<TResult> outc
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome that caused the circuit breaker to be closed.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 

src/Polly.Core/CircuitBreaker/OnCircuitOpenedArguments.cs

@@ -27,12 +27,12 @@ public OnCircuitOpenedArguments(ResilienceContext context, Outcome<TResult> outc
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome that caused the circuit to open.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 

src/Polly.Core/Fallback/FallbackActionArguments.cs

@@ -0,0 +1,34 @@
+namespace Polly.Fallback;
+
+#pragma warning disable CA1815 // Override equals and operator equals on value types
+
+/// <summary>
+/// Arguments used by <see cref="FallbackStrategyOptions{TResult}.FallbackAction"/>.
+/// </summary>
+/// <typeparam name="TResult">The type of result.</typeparam>
+/// <remarks>
+/// Always use the constructor when creating this struct, otherwise we do not guarantee binary compatibility.
+/// </remarks>
+public readonly struct FallbackActionArguments<TResult> : IOutcomeArguments<TResult>
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FallbackActionArguments{TResult}"/> struct.
+    /// </summary>
+    /// <param name="outcome">The context in which the resilience operation or event occurred.</param>
+    /// <param name="context">The outcome of the resilience operation or event.</param>
+    public FallbackActionArguments(ResilienceContext context, Outcome<TResult> outcome)
+    {
+        Context = context;
+        Outcome = outcome;
+    }
+
+    /// <summary>
+    /// Gets the outcome that should be handled by the fallback.
+    /// </summary>
+    public Outcome<TResult> Outcome { get; }
+
+    /// <summary>
+    /// Gets the context of this event.
+    /// </summary>
+    public ResilienceContext Context { get; }
+}

src/Polly.Core/Fallback/FallbackHandler.cs

@@ -2,11 +2,11 @@ namespace Polly.Fallback;
 
 internal sealed record class FallbackHandler<T>(
     Func<FallbackPredicateArguments<T>, ValueTask<bool>> ShouldHandle,
-    Func<FallbackPredicateArguments<T>, ValueTask<Outcome<T>>> ActionGenerator)
+    Func<FallbackActionArguments<T>, ValueTask<Outcome<T>>> ActionGenerator)
 {
-    public async ValueTask<Outcome<TResult>> GetFallbackOutcomeAsync<TResult>(FallbackPredicateArguments<T> args)
+    public async ValueTask<Outcome<TResult>> GetFallbackOutcomeAsync<TResult>(FallbackActionArguments<T> args)
     {
-        var copiedArgs = new FallbackPredicateArguments<T>(
+        var copiedArgs = new FallbackActionArguments<T>(
             args.Context,
             args.Outcome.AsOutcome<T>());
 

src/Polly.Core/Fallback/FallbackPredicateArguments.cs

@@ -23,12 +23,12 @@ public FallbackPredicateArguments(ResilienceContext context, Outcome<TResult> ou
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome of user-callback.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 }

src/Polly.Core/Fallback/FallbackResilienceStrategy.cs

@@ -37,7 +37,7 @@ protected internal override async ValueTask<Outcome<T>> ExecuteCore<TState>(Func
 
         try
         {
-            return await _handler.GetFallbackOutcomeAsync<T>(handleFallbackArgs).ConfigureAwait(context.ContinueOnCapturedContext);
+            return await _handler.GetFallbackOutcomeAsync<T>(new FallbackActionArguments<T>(context, outcome)).ConfigureAwait(context.ContinueOnCapturedContext);
         }
         catch (Exception e)
         {

src/Polly.Core/Fallback/FallbackStrategyOptions.TResult.cs

@@ -29,7 +29,7 @@ public class FallbackStrategyOptions<TResult> : ResilienceStrategyOptions
     /// The default value is <see langword="null"/>. This property is required.
     /// </value>
     [Required]
-    public Func<FallbackPredicateArguments<TResult>, ValueTask<Outcome<TResult>>>? FallbackAction { get; set; }
+    public Func<FallbackActionArguments<TResult>, ValueTask<Outcome<TResult>>>? FallbackAction { get; set; }
 
     /// <summary>
     /// Gets or sets event delegate that is raised when fallback happens.

src/Polly.Core/Fallback/OnFallbackArguments.cs

@@ -23,12 +23,12 @@ public OnFallbackArguments(ResilienceContext context, Outcome<TResult> outcome)
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome that caused the fallback to be executed.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 }

src/Polly.Core/Hedging/Controller/HedgingHandler.cs

@@ -13,9 +13,9 @@ internal sealed record class HedgingHandler<T>(
                 args.PrimaryContext,
                 args.ActionContext,
                 args.AttemptNumber,
-                (Func<ResilienceContext, ValueTask<Outcome<T>>>)(object)args.Callback);
+                args.Callback);
 
-            return (Func<ValueTask<Outcome<T>>>?)(object)ActionGenerator(copiedArgs)!;
+            return ActionGenerator(copiedArgs);
         }
 
         return CreateNonGenericAction(args);

src/Polly.Core/Hedging/HedgingDelayArguments.cs → src/Polly.Core/Hedging/HedgingDelayGeneratorArguments.cs

@@ -8,14 +8,14 @@ namespace Polly.Hedging;
 /// <remarks>
 /// Always use the constructor when creating this struct, otherwise we do not guarantee binary compatibility.
 /// </remarks>
-public readonly struct HedgingDelayArguments
+public readonly struct HedgingDelayGeneratorArguments
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="HedgingDelayArguments"/> struct.
+    /// Initializes a new instance of the <see cref="HedgingDelayGeneratorArguments"/> struct.
     /// </summary>
     /// <param name="context">The context associated with the execution of a user-provided callback.</param>
     /// <param name="attemptNumber">The zero-based hedging attempt number.</param>
-    public HedgingDelayArguments(ResilienceContext context, int attemptNumber)
+    public HedgingDelayGeneratorArguments(ResilienceContext context, int attemptNumber)
     {
         Context = context;
         AttemptNumber = attemptNumber;

src/Polly.Core/Hedging/HedgingPredicateArguments.cs

@@ -23,12 +23,12 @@ public HedgingPredicateArguments(ResilienceContext context, Outcome<TResult> out
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome of user-callback.
     /// </summary>
     public Outcome<TResult> Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 }

src/Polly.Core/Hedging/HedgingResilienceStrategy.cs

@@ -15,7 +15,7 @@ public HedgingResilienceStrategy(
         int maxHedgedAttempts,
         HedgingHandler<T> hedgingHandler,
         Func<OnHedgingArguments<T>, ValueTask>? onHedging,
-        Func<HedgingDelayArguments, ValueTask<TimeSpan>>? hedgingDelayGenerator,
+        Func<HedgingDelayGeneratorArguments, ValueTask<TimeSpan>>? hedgingDelayGenerator,
         TimeProvider timeProvider,
         ResilienceStrategyTelemetry telemetry)
     {
@@ -34,7 +34,7 @@ public HedgingResilienceStrategy(
 
     public int MaxHedgedAttempts { get; }
 
-    public Func<HedgingDelayArguments, ValueTask<TimeSpan>>? HedgingDelayGenerator { get; }
+    public Func<HedgingDelayGeneratorArguments, ValueTask<TimeSpan>>? HedgingDelayGenerator { get; }
 
     public HedgingHandler<T> HedgingHandler { get; }
 
@@ -95,7 +95,7 @@ private async ValueTask<Outcome<T>> ExecuteCoreAsync<TState>(
                 // If completedHedgedTask is null it indicates that we still do not have any finished hedged task within the hedging delay.
                 // We will create additional hedged task in the next iteration.
                 await HandleOnHedgingAsync(
-                    new OnHedgingArguments<T>(context, Outcome.FromResult<T>(default), attempt, hasOutcome: false, duration: delay)).ConfigureAwait(context.ContinueOnCapturedContext);
+                    new OnHedgingArguments<T>(context, null, attempt, duration: delay)).ConfigureAwait(context.ContinueOnCapturedContext);
                 continue;
             }
 
@@ -109,13 +109,13 @@ await HandleOnHedgingAsync(
 
             var executionTime = _timeProvider.GetElapsedTime(start);
             await HandleOnHedgingAsync(
-                new OnHedgingArguments<T>(context, outcome, attempt, hasOutcome: true, executionTime)).ConfigureAwait(context.ContinueOnCapturedContext);
+                new OnHedgingArguments<T>(context, outcome, attempt, executionTime)).ConfigureAwait(context.ContinueOnCapturedContext);
         }
     }
 
     private async ValueTask HandleOnHedgingAsync(OnHedgingArguments<T> args)
     {
-        _telemetry.Report<OnHedgingArguments<T>, T>(new(ResilienceEventSeverity.Warning, HedgingConstants.OnHedgingEventName), args);
+        _telemetry.Report<OnHedgingArguments<T>, T>(new(ResilienceEventSeverity.Warning, HedgingConstants.OnHedgingEventName), args.Context, default, args);
 
         if (OnHedging is not null)
         {
@@ -133,6 +133,6 @@ internal ValueTask<TimeSpan> GetHedgingDelayAsync(ResilienceContext context, int
             return new ValueTask<TimeSpan>(HedgingDelay);
         }
 
-        return HedgingDelayGenerator(new HedgingDelayArguments(context, attempt));
+        return HedgingDelayGenerator(new HedgingDelayGeneratorArguments(context, attempt));
     }
 }

src/Polly.Core/Hedging/HedgingStrategyOptions.TResult.cs

@@ -79,7 +79,7 @@ public class HedgingStrategyOptions<TResult> : ResilienceStrategyOptions
     /// <value>
     /// The default value is <see langword="null"/>.
     /// </value>
-    public Func<HedgingDelayArguments, ValueTask<TimeSpan>>? HedgingDelayGenerator { get; set; }
+    public Func<HedgingDelayGeneratorArguments, ValueTask<TimeSpan>>? HedgingDelayGenerator { get; set; }
 
     /// <summary>
     /// Gets or sets the event that is raised when a hedging is performed.

src/Polly.Core/Hedging/OnHedgingArguments.cs

@@ -9,32 +9,31 @@ namespace Polly.Hedging;
 /// <remarks>
 /// Always use the constructor when creating this struct, otherwise we do not guarantee binary compatibility.
 /// </remarks>
-public readonly struct OnHedgingArguments<TResult> : IOutcomeArguments<TResult>
+public readonly struct OnHedgingArguments<TResult>
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="OnHedgingArguments{TResult}"/> struct.
     /// </summary>
     /// <param name="outcome">The context in which the resilience operation or event occurred.</param>
     /// <param name="context">The outcome of the resilience operation or event.</param>
     /// <param name="attemptNumber">The zero-based hedging attempt number.</param>
-    /// <param name="hasOutcome">Indicates whether outcome is available.</param>
     /// <param name="duration">The execution duration of hedging attempt or the hedging delay in case the attempt was not finished in time.</param>
-    public OnHedgingArguments(ResilienceContext context, Outcome<TResult> outcome, int attemptNumber, bool hasOutcome, TimeSpan duration)
+    public OnHedgingArguments(ResilienceContext context, Outcome<TResult>? outcome, int attemptNumber, TimeSpan duration)
     {
         Context = context;
         Outcome = outcome;
         AttemptNumber = attemptNumber;
-        HasOutcome = hasOutcome;
         Duration = duration;
     }
 
     /// <summary>
-    /// Gets the outcome of the resilience operation or event.
+    /// Gets the outcome that needs to be hedged, if any.
     /// </summary>
-    public Outcome<TResult> Outcome { get; }
+    /// <remarks>If this property is <see langword="null"/>, it's an indication that user-callback or hedged operation did not complete within the hedging delay.</remarks>
+    public Outcome<TResult>? Outcome { get; }
 
     /// <summary>
-    /// Gets the context in which the resilience operation or event occurred.
+    /// Gets the context of this event.
     /// </summary>
     public ResilienceContext Context { get; }
 
@@ -43,14 +42,6 @@ public OnHedgingArguments(ResilienceContext context, Outcome<TResult> outcome, i
     /// </summary>
     public int AttemptNumber { get; }
 
-    /// <summary>
-    /// Gets a value indicating whether the outcome is available before loading the next hedged task.
-    /// </summary>
-    /// <remarks>
-    /// No outcome indicates that the previous action did not finish within the hedging delay.
-    /// </remarks>
-    public bool HasOutcome { get; }
-
     /// <summary>
     /// Gets the execution duration of hedging attempt or the hedging delay in case the attempt was not finished in time.
     /// </summary>