io.github.bucket4j

Class AbstractBucket

java.lang.Object

io.github.bucket4j.AbstractBucket

All Implemented Interfaces:

BlockingBucket, Bucket

Direct Known Subclasses:

GridBucket, LockFreeBucket, SynchronizedBucket

public abstract class AbstractBucket
extends Object
implements Bucket, BlockingBucket

Constructor Summary

Constructors

Constructor and Description
AbstractBucket(BucketListener listener)

Method Summary

Modifier and Type	Method and Description
void	addTokens(long tokensToAdd) Add tokensToAdd to bucket.
protected abstract CompletableFuture<Void>	addTokensAsyncImpl(long tokensToAdd)
protected abstract void	addTokensImpl(long tokensToAdd)
AsyncBucket	asAsync() Returns asynchronous view of this bucket.
AsyncScheduledBucket	asAsyncScheduler() Returns asynchronous view of this bucket that allows to use bucket as async scheduler.
BlockingBucket	asScheduler() Returns the BlockingBucket view of this bucket, that provides operations which are able to block caller thread.
void	consume(long tokensToConsume, BlockingStrategy blockingStrategy) Consumes a specified number of tokens from the bucket.
protected abstract long	consumeAsMuchAsPossibleImpl(long limit)
void	consumeUninterruptibly(long tokensToConsume, UninterruptibleBlockingStrategy blockingStrategy) Has same semantic with BlockingBucket.consume(long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).
void	replaceConfiguration(BucketConfiguration newConfiguration) Replaces configuration of this bucket instance.
protected abstract CompletableFuture<Void>	replaceConfigurationAsyncImpl(BucketConfiguration newConfiguration)
protected abstract void	replaceConfigurationImpl(BucketConfiguration newConfiguration)
protected abstract CompletableFuture<Long>	reserveAndCalculateTimeToSleepAsyncImpl(long tokensToConsume, long maxWaitTimeNanos)
protected abstract long	reserveAndCalculateTimeToSleepImpl(long tokensToConsume, long waitIfBusyNanos)
boolean	tryConsume(long tokensToConsume) Tries to consume a specified number of tokens from this bucket.
boolean	tryConsume(long tokensToConsume, long maxWaitTimeNanos, BlockingStrategy blockingStrategy) Tries to consume a specified number of tokens from the bucket.
ConsumptionProbe	tryConsumeAndReturnRemaining(long tokensToConsume) Tries to consume a specified number of tokens from this bucket.
protected abstract CompletableFuture<ConsumptionProbe>	tryConsumeAndReturnRemainingTokensAsyncImpl(long tokensToConsume)
protected abstract ConsumptionProbe	tryConsumeAndReturnRemainingTokensImpl(long tokensToConsume)
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.
protected abstract CompletableFuture<Long>	tryConsumeAsMuchAsPossibleAsyncImpl(long limit)
protected abstract CompletableFuture<Boolean>	tryConsumeAsyncImpl(long tokensToConsume)
protected abstract boolean	tryConsumeImpl(long tokensToConsume)
boolean	tryConsumeUninterruptibly(long tokensToConsume, long maxWaitTimeNanos, UninterruptibleBlockingStrategy blockingStrategy) Has same semantic with BlockingBucket.tryConsume(long, long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.github.bucket4j.Bucket

createSnapshot, getAvailableTokens, isAsyncModeSupported, toListenable

Methods inherited from interface io.github.bucket4j.BlockingBucket

consume, consumeUninterruptibly, tryConsume, tryConsume, tryConsume, tryConsumeUninterruptibly, tryConsumeUninterruptibly, tryConsumeUninterruptibly

Constructor Detail

AbstractBucket

public AbstractBucket(BucketListener listener)

Method Detail

consumeAsMuchAsPossibleImpl

protected abstract long consumeAsMuchAsPossibleImpl(long limit)

tryConsumeImpl

protected abstract boolean tryConsumeImpl(long tokensToConsume)

tryConsumeAndReturnRemainingTokensImpl

protected abstract ConsumptionProbe tryConsumeAndReturnRemainingTokensImpl(long tokensToConsume)

reserveAndCalculateTimeToSleepImpl

protected abstract long reserveAndCalculateTimeToSleepImpl(long tokensToConsume,
                                                           long waitIfBusyNanos)

addTokensImpl

protected abstract void addTokensImpl(long tokensToAdd)

tryConsumeAsMuchAsPossibleAsyncImpl

protected abstract CompletableFuture<Long> tryConsumeAsMuchAsPossibleAsyncImpl(long limit)

tryConsumeAsyncImpl

protected abstract CompletableFuture<Boolean> tryConsumeAsyncImpl(long tokensToConsume)

tryConsumeAndReturnRemainingTokensAsyncImpl

protected abstract CompletableFuture<ConsumptionProbe> tryConsumeAndReturnRemainingTokensAsyncImpl(long tokensToConsume)

reserveAndCalculateTimeToSleepAsyncImpl

protected abstract CompletableFuture<Long> reserveAndCalculateTimeToSleepAsyncImpl(long tokensToConsume,
                                                                                   long maxWaitTimeNanos)

addTokensAsyncImpl

protected abstract CompletableFuture<Void> addTokensAsyncImpl(long tokensToAdd)

replaceConfigurationImpl

protected abstract void replaceConfigurationImpl(BucketConfiguration newConfiguration)

replaceConfigurationAsyncImpl

protected abstract CompletableFuture<Void> replaceConfigurationAsyncImpl(BucketConfiguration newConfiguration)

asAsync

public AsyncBucket asAsync()

Description copied from interface: Bucket

Returns asynchronous view of this bucket.

If asynchronous mode is not supported by particular extension behind this bucket, then any attempt to call this method will fail with UnsupportedOperationException.

Specified by:

asAsync in interface Bucket

Returns:

Asynchronous view of this bucket.

asAsyncScheduler

public AsyncScheduledBucket asAsyncScheduler()

Description copied from interface: Bucket

Returns asynchronous view of this bucket that allows to use bucket as async scheduler.

If asynchronous mode is not supported by particular extension behind this bucket, then any attempt to call this method will fail with UnsupportedOperationException.

Specified by:

asAsyncScheduler in interface Bucket

Returns:

Asynchronous view of this bucket that allows to use bucket as async scheduler.

asScheduler

public BlockingBucket asScheduler()

Description copied from interface: Bucket

Returns the BlockingBucket view of this bucket, that provides operations which are able to block caller thread.

Specified by:

asScheduler in interface Bucket

Returns:

the view to bucket that can be used as scheduler

tryConsume

public boolean tryConsume(long tokensToConsume)

Description copied from interface: Bucket

Tries to consume a specified number of tokens from this bucket.

Specified by:

tryConsume in interface Bucket

Parameters:

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

Returns:

true if the tokens were consumed, false otherwise.

tryConsume

public boolean tryConsume(long tokensToConsume,
                          long maxWaitTimeNanos,
                          BlockingStrategy blockingStrategy)
                   throws InterruptedException

Description copied from interface: BlockingBucket

Tries to consume a specified number of tokens from the bucket.

The algorithm is following:

• If bucket has enough tokens, then tokens consumed and true returned immediately.
• If bucket has no enough tokens, and required amount of tokens can not be refilled, even after waiting of maxWaitTimeNanos nanoseconds, then consumes nothing and returns false immediately.
• If bucket has no enough tokens, but deficit can be closed in period of time less then maxWaitTimeNanos nanoseconds, then tokens consumed(reserved in fair manner) 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 Bucket.addTokens(long) to returned tokens back.

Specified by:

tryConsume in interface BlockingBucket

Parameters:

tokensToConsume - The number of tokens to consume 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 bucket

Returns:

true if numTokens has been consumed or false when numTokens has not been consumed

Throws:

InterruptedException - in case of current thread has been interrupted during the waiting

tryConsumeUninterruptibly

public boolean tryConsumeUninterruptibly(long tokensToConsume,
                                         long maxWaitTimeNanos,
                                         UninterruptibleBlockingStrategy blockingStrategy)

Description copied from interface: BlockingBucket

Has same semantic with BlockingBucket.tryConsume(long, long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).

Specified by:

tryConsumeUninterruptibly in interface BlockingBucket

Parameters:

tokensToConsume - The number of tokens to consume 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 bucket

Returns:

true if numTokens has been consumed or false when numTokens has not been consumed

See Also:

BlockingBucket.tryConsume(long, long, BlockingStrategy)

consume

public void consume(long tokensToConsume,
                    BlockingStrategy blockingStrategy)
             throws InterruptedException

Description copied from interface: BlockingBucket

Consumes a specified number of tokens from the bucket.

The algorithm is following:

• If bucket has enough tokens, then tokens consumed and method returns immediately.
• If bucket has no enough tokens, then required amount of tokens will be reserved for future consumption and current thread will be blocked for a time required to close deficit.
• Note: If InterruptedException happen when thread was blocked then tokens will be not returned back to bucket, but you can use Bucket.addTokens(long) to returned tokens back.

Specified by:

consume in interface BlockingBucket

Parameters:

tokensToConsume - The number of tokens to consume from the bucket.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

Throws:

InterruptedException - in case of current thread has been interrupted during the waiting

consumeUninterruptibly

public void consumeUninterruptibly(long tokensToConsume,
                                   UninterruptibleBlockingStrategy blockingStrategy)

Description copied from interface: BlockingBucket

Has same semantic with BlockingBucket.consume(long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).

Specified by:

consumeUninterruptibly in interface BlockingBucket

Parameters:

tokensToConsume - The number of tokens to consume from the bucket.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

See Also:

BlockingBucket.consume(long, BlockingStrategy)

tryConsumeAsMuchAsPossible

public long tryConsumeAsMuchAsPossible(long limit)

Description copied from interface: Bucket

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.

Specified by:

tryConsumeAsMuchAsPossible in interface Bucket

Parameters:

limit - maximum number of tokens to consume, should be positive.

Returns:

number of tokens which has been consumed, or zero if was consumed nothing.

tryConsumeAsMuchAsPossible

public long tryConsumeAsMuchAsPossible()

Description copied from interface: Bucket

Tries to consume as much tokens from this bucket as available at the moment of invocation.

Specified by:

tryConsumeAsMuchAsPossible in interface Bucket

Returns:

number of tokens which has been consumed, or zero if was consumed nothing.

tryConsumeAndReturnRemaining

public ConsumptionProbe tryConsumeAndReturnRemaining(long tokensToConsume)

Description copied from interface: Bucket

Tries to consume a specified number of tokens from this bucket.

Specified by:

tryConsumeAndReturnRemaining in interface Bucket

Parameters:

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

Returns:

ConsumptionProbe which describes both result of consumption and tokens remaining in the bucket after consumption.

addTokens

public void addTokens(long tokensToAdd)

Description copied from interface: Bucket

Add tokensToAdd to bucket. Resulted count of tokens are calculated by following formula:

newTokens = Math.min(capacity, currentTokens + tokensToAdd)

in other words resulted number of tokens never exceeds capacity independent of tokensToAdd.

Example of usage

The "compensating transaction" is one of obvious use case, when any piece of code consumed tokens from bucket, tried to do something and failed, the "addTokens" will be helpful to return tokens back to bucket:

      Bucket wallet;
      ...
      if(wallet.tryConsume(50)) {// get 50 cents from wallet
         try {
             buyCocaCola();
         } catch(NoCocaColaException e) {
             // return money to wallet
             wallet.addTokens(50);
         }
      };
 

Specified by:

addTokens in interface Bucket

Parameters:

tokensToAdd - number of tokens to add

replaceConfiguration

public void replaceConfiguration(BucketConfiguration newConfiguration)

Description copied from interface: Bucket

Replaces configuration of this bucket instance.

Rules of reconfiguration:

• New configuration can be applied if and only if it describes same count of bandwidths which already configured, else 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 vice-versa.
• If new configuration defines capacity which greater than current available tokens, then current available tokens stay unchanged.
• If new configuration defines capacity which lesser than current available tokens, then current available tokens will be reduced to capacity. For example: if bandwidth at moment of reconfiguration has 90 tokens, and new capacity is 70 tokens then available tokens will be reduced from 90 to 70 according to new rules.

Specified by:

replaceConfiguration in interface Bucket

Parameters:

newConfiguration - the new configuration for this bucket