Class CircularBufferTokenBucket

A circular buffer keeps track of tokens. The value of each buffer index represents the number of requests sent during that time period and as time passes, old indices are zeroed and the current index advances.The entire length of the buffer minus one represents a entire timespan (each index represents a fraction of the total timespan). The extra index prevents violations due to bucket misalignment.A rolling total is kept of the buffer's contents.

When trying to obtain a token, we first check the rolling total is less than the limit.If so, we obtain a token by incrementing the rolling total and incrementing the buffer's current index.

The length of the buffer is one more than the temporal factor supplied to the constructor. The temporal factor represents the multiplicative increase in temporal resolution provided with more buffer indices.

Additionally, a non-zero spreading factor can be provided to prevent a single index from supplying all of a timespan's tokens. A spreading factor of 0.0 means no spreading, a factor of 0.5 means each index can supply up to half of the tokens, and a factor of 1.0 means tokens will be evenly supplied by all indices (provided there is enough demand).

Checking the availability of tokens is done using the {@link #getDelay()} method. Tokens are obtained using the {@link #getToken()} method. Both these methods are synchronized on the bucket instance. Because the state of the bucket may change if there are multiple threads, it is best to call these methods in a synchronized block, as shown below.

ITokenBucket bucket = ...;
while (true)
{
    long delay;
    synchronized(bucket) {
        delay = bucket.getDelay();
        if (delay == -1)
        {
            bucket.GetTokens(1);
            break;
        }
    }
    // Waiting is done outside of the synchronized block.
    Thread.sleep(delay);
}
// Token is obtained.
...
Inheritance
System.Object
CircularBufferTokenBucket
Implements
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: MingweiSamuel.Camille.Util
Assembly: Camille.dll
Syntax
public class CircularBufferTokenBucket : ITokenBucket

Constructors

| Improve this Doc View Source

CircularBufferTokenBucket(TimeSpan, Int32, Int32, Single, Single)

Main constructor.

Declaration
public CircularBufferTokenBucket(TimeSpan timeSpan, int totalLimit, int temporalFactor, float spreadFactor, float totalLimitFactor)
Parameters
Type Name Description
System.TimeSpan timeSpan

Timespan of this bucket.
System.Int32 totalLimit

Total limit of this bucket.
System.Int32 temporalFactor

Temporal multiplier corresponding to token time tracking.
System.Single spreadFactor

Factor corresponding to token supply spread (from multiple indices).
System.Single totalLimitFactor

Factor to multiply adjustedTotalLimit by to decrease the chance of hitting the rate limit.
| Improve this Doc View Source

CircularBufferTokenBucket(TimeSpan, Int32, Int32, Single, Single, Func<Int64>)

Secondary constructor, mainly for debugging.

Declaration
public CircularBufferTokenBucket(TimeSpan timeSpan, int totalLimit, int temporalFactor, float spreadFactor, float totalLimitFactor, Func<long> tickSupplier)
Parameters
Type Name Description
System.TimeSpan timeSpan

Timespan of this bucket.
System.Int32 totalLimit

Total limit of this bucket.
System.Int32 temporalFactor

Temporal multiplier corresponding to token time tracking.
System.Single spreadFactor

Factor corresponding to token supply spread (from multiple indices).
System.Single totalLimitFactor

Factor to multiply adjustedTotalLimit by to decrease the chance of hitting the rate limit.
System.Func<System.Int64> tickSupplier

Supplies non-descending tick time, useful for debugging.

Methods

| Improve this Doc View Source

GetDelay()

Gets the delay till next available token, or -1 if available.

Declaration
public long GetDelay()
Returns
Type Description
System.Int64

Delay in ticks, or -1 if available.
| Improve this Doc View Source

GetTickSpan()

Declaration
public long GetTickSpan()
Returns
Type Description
System.Int64
| Improve this Doc View Source

GetTokens(Int32)

Gets n tokens, regardless of whether they are available.

Declaration
public bool GetTokens(int n)
Parameters
Type Name Description
System.Int32 n

Number of tokens to get.
Returns
Type Description
System.Boolean

True if the tokens were obtained without violating limits, false otherwise.
| Improve this Doc View Source

GetTotalLimit()

Declaration
public int GetTotalLimit()
Returns
Type Description
System.Int32

Implements

Extension Methods