| | | 1 | | namespace ArturRios.Util.FlowControl.Waiter; |
| | | 2 | | |
| | | 3 | | /// <summary> |
| | | 4 | | /// Implements an exponential backoff waiting strategy with jitter to reduce contention. |
| | | 5 | | /// </summary> |
| | | 6 | | /// <remarks> |
| | | 7 | | /// Wait times grow exponentially (2^n seconds base minus a fixed delay) and a random jitter is added. |
| | | 8 | | /// Call <see cref="WaitAsync"/> before each retry attempt until <see cref="CanRetry"/> is false. |
| | | 9 | | /// Every wait is clamped to <see cref="MaxWaitMilliseconds"/>, so a large |
| | | 10 | | /// <paramref name="maxRetryCount"/> produces a long series of capped waits rather than an arithmetic |
| | | 11 | | /// overflow or a multi-day sleep. |
| | | 12 | | /// </remarks> |
| | | 13 | | /// <param name="maxRetryCount">Maximum number of retries allowed; must not be negative.</param> |
| | | 14 | | /// <param name="maxWaitMilliseconds"> |
| | | 15 | | /// Upper bound applied to a single wait, in milliseconds. Defaults to |
| | | 16 | | /// <see cref="DefaultMaxWaitMilliseconds"/> (30 seconds); must be greater than zero. |
| | | 17 | | /// </param> |
| | | 18 | | /// <exception cref="ArgumentOutOfRangeException"> |
| | | 19 | | /// <paramref name="maxRetryCount"/> is negative, or <paramref name="maxWaitMilliseconds"/> is not positive. |
| | | 20 | | /// </exception> |
| | 10 | 21 | | public class JitteredWaiter(int maxRetryCount, int maxWaitMilliseconds = JitteredWaiter.DefaultMaxWaitMilliseconds) |
| | | 22 | | { |
| | | 23 | | /// <summary> |
| | | 24 | | /// Default ceiling for a single wait: 30 seconds. |
| | | 25 | | /// </summary> |
| | | 26 | | public const int DefaultMaxWaitMilliseconds = 30_000; |
| | | 27 | | |
| | 14 | 28 | | private readonly Lock _lock = new(); |
| | | 29 | | |
| | | 30 | | /// <summary> |
| | | 31 | | /// Maximum number of retries permitted. |
| | | 32 | | /// </summary> |
| | 99 | 33 | | public int MaxRetryCount { get; } = maxRetryCount >= 0 |
| | 14 | 34 | | ? maxRetryCount |
| | 14 | 35 | | : throw new ArgumentOutOfRangeException(nameof(maxRetryCount), maxRetryCount, "Value must not be negative."); |
| | | 36 | | |
| | | 37 | | /// <summary> |
| | | 38 | | /// Ceiling applied to a single wait, in milliseconds. |
| | | 39 | | /// </summary> |
| | 90 | 40 | | public int MaxWaitMilliseconds { get; } = maxWaitMilliseconds > 0 |
| | 12 | 41 | | ? maxWaitMilliseconds |
| | 12 | 42 | | : throw new ArgumentOutOfRangeException(nameof(maxWaitMilliseconds), maxWaitMilliseconds, "Value must be greater |
| | | 43 | | |
| | 241 | 44 | | private int Count { get; set; } |
| | | 45 | | |
| | | 46 | | /// <summary> |
| | | 47 | | /// Indicates whether another retry attempt can be performed. |
| | | 48 | | /// </summary> |
| | | 49 | | public bool CanRetry |
| | | 50 | | { |
| | | 51 | | get |
| | 5 | 52 | | { |
| | | 53 | | lock (_lock) |
| | | 54 | | { |
| | 5 | 55 | | return Count < MaxRetryCount; |
| | | 56 | | } |
| | 5 | 57 | | } |
| | | 58 | | } |
| | | 59 | | |
| | | 60 | | /// <summary> |
| | | 61 | | /// Asynchronously waits based on the current retry attempt using exponential backoff with jitter. |
| | | 62 | | /// </summary> |
| | | 63 | | /// <param name="cancellationToken">Cancels the wait.</param> |
| | | 64 | | /// <exception cref="MaxRetriesReachedException">Thrown when called more times than <see cref="MaxRetryCount"/>.</ex |
| | | 65 | | /// <exception cref="OperationCanceledException"><paramref name="cancellationToken"/> was canceled.</exception> |
| | | 66 | | public async Task WaitAsync(CancellationToken cancellationToken = default) |
| | 80 | 67 | | { |
| | | 68 | | int currentRetryAttempt; |
| | | 69 | | |
| | | 70 | | lock (_lock) |
| | | 71 | | { |
| | 80 | 72 | | if (Count >= MaxRetryCount) |
| | | 73 | | { |
| | 2 | 74 | | throw new MaxRetriesReachedException(); |
| | | 75 | | } |
| | | 76 | | |
| | 78 | 77 | | currentRetryAttempt = Count++; |
| | 78 | 78 | | } |
| | | 79 | | |
| | 78 | 80 | | await Task.Delay(Backoff.DelayFor(currentRetryAttempt, MaxWaitMilliseconds), cancellationToken).ConfigureAwait(f |
| | 76 | 81 | | } |
| | | 82 | | } |