Package com.illumon.util

Class TokenBucketThrottle

java.lang.Object

com.illumon.util.TokenBucketThrottle

public class TokenBucketThrottle
extends Object

A simple implementation of a Token Bucket algorithm for throttling. This implementation guarantees "fairness" of allocations, in that the resource requests will be granted in the order in which they were requested. If there are multiple outstanding requests at one time, then the order in which they continue processing can not be guaranteed as they will be released in order, but since they must be from different threads, the processing order can not be guaranteed.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TokenBucketThrottle.WaitElement

Constructor Summary

Constructors

Constructor	Description
TokenBucketThrottle(long intervalInNanos, long tokensPerInterval, long maxCapacity, com.fishlib.base.stats.Counter delayStatsCounter)

Method Summary

Modifier and Type	Method	Description
long	consume(long amount, TokenBucketThrottle.WaitElement reusableWaitElement)	Consume the specified number of tokens.
long	getTokensPerSecond()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TokenBucketThrottle

public TokenBucketThrottle(long intervalInNanos, long tokensPerInterval, long maxCapacity, com.fishlib.base.stats.Counter delayStatsCounter)

Method Details

consume

public long consume(long amount, TokenBucketThrottle.WaitElement reusableWaitElement)

Consume the specified number of tokens. In this implementation, the order in which grants are given will be strictly maintained, although the order in which threads will resume can not be guaranteed. - - If nobody is waiting: -- The appropriate number of tokens is added to the available capacity based on the time since the last consume call -- If the capacity is available, the amount will be subtracted from the available capacity and the method will return -- If the capacity is not available, the request will be added to the queue and this thread will return when capacity is available - If anybody is currently waiting, the request will be added to the end of the queue and will return when capacity is available - If the requested capacity exceeds the maximum possible bucket capacity, an exception will be thrown because the request can never succeed

Parameters:

amount - the number of tokens to consume

reusableWaitElement - if desired, provide a reusable waitElement so they don't need to continually be reallocated; if supplied, the caller must ensure that these are NOT shared across threads or the algorithm will break

Returns:

the milliseconds spent waiting for the request; 0 means that no wait was required

Throws:

IllegalArgumentException - if the request exceeds the maximum bucket capacity

getTokensPerSecond

public long getTokensPerSecond()