org.isomorphism.util

Interface TokenBucket

public interface TokenBucket

A token bucket is used for rate limiting access to a portion of code.

See Also:

Token Bucket on Wikipedia, Leaky Bucket on Wikipedia

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TokenBucket.RefillStrategy Encapsulation of a refilling strategy for a token bucket.
static interface	TokenBucket.SleepStrategy Encapsulation of a strategy for relinquishing control of the CPU.

Method Summary

Modifier and Type	Method and Description
void	consume() Consume a single token from the bucket.
void	consume(long numTokens) Consumes multiple tokens from the bucket.
long	getCapacity() Returns the capacity of this token bucket.
long	getDurationUntilNextRefill(TimeUnit unit) Returns the amount of time in the specified time unit until the next group of tokens can be added to the token bucket.
long	getNumTokens() Returns the current number of tokens in the bucket.
void	refill(long numTokens) Refills the bucket with the specified number of tokens.
boolean	tryConsume() Attempt to consume a single token from the bucket.
boolean	tryConsume(long numTokens) Attempt to consume a specified number of tokens from the bucket.

Method Detail

getCapacity

long getCapacity()

Returns the capacity of this token bucket. This is the maximum number of tokens that the bucket can hold at any one time.

Returns:

The capacity of the bucket.

getNumTokens

long getNumTokens()

Returns the current number of tokens in the bucket. If the bucket is empty then this method will return 0.

Returns:

The current number of tokens in the bucket.

getDurationUntilNextRefill

long getDurationUntilNextRefill(TimeUnit unit)
                         throws UnsupportedOperationException

Returns the amount of time in the specified time unit until the next group of tokens can be added to the token bucket.

Parameters:

unit - The time unit to express the return value in.

Returns:

The amount of time until the next group of tokens can be added to the token bucket.

Throws:

UnsupportedOperationException

See Also:

TokenBucket.RefillStrategy.getDurationUntilNextRefill(java.util.concurrent.TimeUnit)

tryConsume

boolean tryConsume()

Attempt to consume a single token from the bucket. If it was consumed then true is returned, otherwise false is returned.

Returns:

true if a token was consumed, false otherwise.

tryConsume

boolean tryConsume(long numTokens)

Attempt to consume a specified number of tokens from the bucket. If the tokens were consumed then true is returned, otherwise false is returned.

Parameters:

numTokens - The number of tokens to consume from the bucket, must be a positive number.

Returns:

true if the tokens were consumed, false otherwise.

consume

void consume()

Consume a single token from the bucket. If no token is currently available then this method will block until a token becomes available.

consume

void consume(long numTokens)

Consumes multiple tokens from the bucket. If enough tokens are not currently available then this method will block until

Parameters:

numTokens - The number of tokens to consume from teh bucket, must be a positive number.

refill

void refill(long numTokens)

Refills the bucket with the specified number of tokens. If the bucket is currently full or near capacity then fewer than numTokens may be added.

Parameters:

numTokens - The number of tokens to add to the bucket.