public interface Bucket
Use following links for further details:
Modifier and Type | Method and Description |
---|---|
void |
addTokens(long tokensToAdd)
Add tokensToAdd to bucket.
|
AsyncBucket |
asAsync()
Gets asynchronous view of this bucket.
|
BucketState |
createSnapshot()
Creates the copy of internal state.
|
long |
getAvailableTokens()
Returns amount of available tokens in this bucket.
|
BucketConfiguration |
getConfiguration()
Returns configuration of this bucket.
|
boolean |
isAsyncModeSupported()
Describes whether or not this bucket supports asynchronous mode.
|
void |
replaceConfiguration(BucketConfiguration newConfiguration)
Replaces configuration of this bucket instance.
|
boolean |
tryConsume(long numTokens)
Tries to consume a specified number of tokens from this bucket.
|
boolean |
tryConsume(long numTokens,
long maxWaitTimeNanos,
BlockingStrategy blockingStrategy)
Tries to consumes a specified number of tokens from the bucket.
|
ConsumptionProbe |
tryConsumeAndReturnRemaining(long numTokens)
Tries to consume a specified number of tokens from this bucket.
|
long |
tryConsumeAsMuchAsPossible()
Tries to consume as much tokens from this bucket as available at the moment of invocation.
|
long |
tryConsumeAsMuchAsPossible(long limit)
Tries to consume as much tokens from bucket as available in the bucket at the moment of invocation,
but tokens which should be consumed is limited by
limit . |
boolean |
tryConsumeUninterruptibly(long numTokens,
long maxWaitTimeNanos,
BlockingStrategy blockingStrategy)
Has same semantic with
tryConsume(long, long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit). |
boolean isAsyncModeSupported()
If asynchronous mode is not supported any attempt to call asAsync()
will fail with UnsupportedOperationException
AsyncBucket asAsync()
If asynchronous mode is not supported by particular extension behind this bucket,
then any attempt to call this method will fail with UnsupportedOperationException
.
UnsupportedOperationException
- if particular extension behind the bucket does not support asynchronous mode.boolean tryConsume(long numTokens)
numTokens
- The number of tokens to consume from the bucket, must be a positive number.true
if the tokens were consumed, false
otherwise.ConsumptionProbe tryConsumeAndReturnRemaining(long numTokens)
numTokens
- The number of tokens to consume from the bucket, must be a positive number.ConsumptionProbe
which describes both result of consumption and tokens remaining in the bucket after consumption.long tryConsumeAsMuchAsPossible()
long tryConsumeAsMuchAsPossible(long limit)
limit
.limit
- maximum number of tokens to consume, should be positive.boolean tryConsume(long numTokens, long maxWaitTimeNanos, BlockingStrategy blockingStrategy) throws InterruptedException
The algorithm is following:
maxWaitTimeNanos
nanoseconds,
then consumes nothing and returns false immediately.
maxWaitTimeNanos
nanoseconds,
then tokens consumed from bucket and current thread blocked for a time required to close deficit,
after unblocking method returns true.
Note: If InterruptedException happen when thread was blocked
then tokens will be not returned back to bucket,
but you can use addTokens(long)
to returned tokens back.
numTokens
- The number of tokens to tryConsume from the bucket.maxWaitTimeNanos
- limit of time(in nanoseconds) which thread can wait.blockingStrategy
- specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucketnumTokens
has been consumed or false when numTokens
has not been consumedInterruptedException
- in case of current thread has been interrupted during the waitingboolean tryConsumeUninterruptibly(long numTokens, long maxWaitTimeNanos, BlockingStrategy blockingStrategy)
tryConsume(long, long, BlockingStrategy)
but ignores interrupts(just restores interruption flag on exit).numTokens
- The number of tokens to consume from the bucket.maxWaitTimeNanos
- limit of time which thread can wait.blockingStrategy
- specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucketnumTokens
has been consumed or false when numTokens
has not been consumedtryConsume(long, long, BlockingStrategy)
void addTokens(long tokensToAdd)
newTokens = Math.min(capacity, currentTokens + tokensToAdd)in other words resulted number of tokens never exceeds capacity independent of tokensToAdd.
Bucket wallet;
...
if(wallet.tryConsume(50)) {// get 50 cents from wallet
try {
buyCocaCola();
} catch(NoCocaColaException e) {
// return money to wallet
wallet.addTokens(50);
}
};
tokensToAdd
- number of tokens to addlong getAvailableTokens()
This method designed to be used only for monitoring and testing, you should never use this method for business cases, because available tokens can be changed by concurrent transactions for case of multithreaded/multi-process environment.
void replaceConfiguration(BucketConfiguration newConfiguration)
Rules of reconfiguration:
IncompatibleConfigurationException
will be thrown.
In other words you must not try to reduce or increase count of bandwidths,
it is impossible to create bucket with one bandwidth and reconfigure to use two bandwidths and wise versa.
newConfiguration
- the new configuration for this bucketIncompatibleConfigurationException
- if newConfiguration
incompatible with previous configurationBucketState createSnapshot()
This method is designed to be used only for monitoring and testing, you should never use this method for business cases.
BucketConfiguration getConfiguration()
Copyright © 2017. All rights reserved.