Class RetryBudget

Namespace

Kevlar

Assembly

Kevlar.dll

Shares a feedback throttle or replenishing attempt allowance across retries and hedges.

public sealed class RetryBudget

Inheritance

object

RetryBudget

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

The constructor creates a feedback throttle. Its balance starts at MaxTokens. A handled failure subtracts one token; an acceptable successful result adds TokenRatio, bounded by the capacity. Additional attempts are allowed only above half capacity. Initial attempts are never gated. Use CreateReplenishing(int, TimeSpan, TimeProvider?) for an atomic allowance consumed by additional attempts instead. Neither mode limits initial attempts or the number of attempts already in flight.

Constructors

RetryBudget(int, double)

Creates a shared budget with positive capacity and a finite success refund of at least 0.001.

public RetryBudget(int maxTokens = 100, double tokenRatio = 0.1)

Parameters

maxTokens int

Maximum token balance. Default 100.

tokenRatio double

Tokens restored by each acceptable success, rounded down to three decimal places and capped at capacity. Default 0.1.

Properties

AllowsAdditionalAttempt

Whether a feedback balance exceeds half capacity, or a replenishing allowance has a token available.

public bool AllowsAdditionalAttempt { get; }

Property Value

bool

Remarks

This is a snapshot, not a reservation. Strategies atomically acquire replenishing tokens at admission.

MaxTokens

The maximum token balance.

public int MaxTokens { get; }

Property Value

int

ReplenishmentPeriod

The fixed replenishment period, or null for a feedback throttle.

public TimeSpan? ReplenishmentPeriod { get; }

Property Value

TimeSpan?

TokenRatio

The token refund for an acceptable successful result, or zero for a replenishing allowance.

public double TokenRatio { get; }

Property Value

double

Tokens

A thread-safe snapshot of the current balance, between zero and MaxTokens.

public double Tokens { get; }

Property Value

double

Methods

CreateReplenishing(int, TimeSpan, TimeProvider?)

Creates an atomic allowance for additional attempts, replenished in fixed monotonic windows.

public static RetryBudget CreateReplenishing(int maxTokens, TimeSpan replenishmentPeriod, TimeProvider? timeProvider = null)

Parameters

maxTokens int

Positive number of additional attempts available in each window.

replenishmentPeriod TimeSpan

Positive window duration, anchored at budget creation.

timeProvider TimeProvider

Clock owned by the budget, independent of shield clocks. Null uses System.

Returns

RetryBudget

A shared budget that starts full and refills lazily without a background timer.

Remarks

Initial attempts are free. Each admitted retry or hedge consumes one token before its continuation or generated action starts. Cancellation before admission consumes nothing; cancellation or downstream rejection after admission does not refund the token. Outcomes do not change the balance. Nested strategies charge only their own additional attempts. Fixed windows can admit bursts across a boundary; combine with rate or concurrency limits when required.