Module io.github.bucket4j.core

Package io.github.bucket4j

Interface BlockingBucket

All Known Implementing Classes:

AbstractBucket, DefaultBucketProxy, LockFreeBucket, SynchronizedBucket, ThreadUnsafeBucket

public interface BlockingBucket

Provides blocking API for bucket that allows to use bucket as scheduler.

Method Summary

Modifier and Type	Method	Description
default void	consume(long numTokens)	This is just overloaded equivalent of consume(long, BlockingStrategy)
void	consume(long numTokens, BlockingStrategy blockingStrategy)	Consumes a specified number of tokens from the bucket.
default void	consumeUninterruptibly(long numTokens)	This is just overloaded equivalent of consumeUninterruptibly(long, UninterruptibleBlockingStrategy)
void	consumeUninterruptibly(long numTokens, UninterruptibleBlockingStrategy blockingStrategy)	Has same semantic with consume(long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).
default boolean	tryConsume(long numTokens, long maxWaitTimeNanos)	This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)
boolean	tryConsume(long numTokens, long maxWaitTimeNanos, BlockingStrategy blockingStrategy)	Tries to consume a specified number of tokens from the bucket.
default boolean	tryConsume(long numTokens, Duration maxWait)	This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)
default boolean	tryConsume(long numTokens, Duration maxWait, BlockingStrategy blockingStrategy)	This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)
default boolean	tryConsumeUninterruptibly(long numTokens, long maxWaitTimeNanos)	This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)
boolean	tryConsumeUninterruptibly(long numTokens, long maxWaitTimeNanos, UninterruptibleBlockingStrategy blockingStrategy)	Has same semantic with tryConsume(long, long, BlockingStrategy) but ignores interrupts(just restores interruption flag on exit).
default boolean	tryConsumeUninterruptibly(long numTokens, Duration maxWait)	This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)
default boolean	tryConsumeUninterruptibly(long numTokens, Duration maxWait, UninterruptibleBlockingStrategy blockingStrategy)	This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

Method Detail

tryConsume

boolean tryConsume(long numTokens,
                   long maxWaitTimeNanos,
                   BlockingStrategy blockingStrategy)
            throws InterruptedException

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.

Parameters:

numTokens - 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

tryConsume

default boolean tryConsume(long numTokens,
                           Duration maxWait,
                           BlockingStrategy blockingStrategy)
                    throws InterruptedException

This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)

Parameters:

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

maxWait - 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 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

See Also:

tryConsume(long, long, BlockingStrategy)

tryConsume

default boolean tryConsume(long numTokens,
                           long maxWaitTimeNanos)
                    throws InterruptedException

This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)

Parameters:

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

maxWaitTimeNanos - limit of time(in nanoseconds) which thread can wait.

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

See Also:

tryConsume(long, long, BlockingStrategy)

tryConsume

default boolean tryConsume(long numTokens,
                           Duration maxWait)
                    throws InterruptedException

This is just overloaded equivalent of tryConsume(long, long, BlockingStrategy)

Parameters:

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

maxWait - limit of time which thread can wait.

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

See Also:

tryConsume(long, long, BlockingStrategy)

tryConsumeUninterruptibly

boolean tryConsumeUninterruptibly(long numTokens,
                                  long maxWaitTimeNanos,
                                  UninterruptibleBlockingStrategy blockingStrategy)

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

Parameters:

numTokens - 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:

tryConsume(long, long, BlockingStrategy)

tryConsumeUninterruptibly

default boolean tryConsumeUninterruptibly(long numTokens,
                                          Duration maxWait,
                                          UninterruptibleBlockingStrategy blockingStrategy)

This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

Parameters:

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

maxWait - 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 bucket

Returns:

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

See Also:

tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

tryConsumeUninterruptibly

default boolean tryConsumeUninterruptibly(long numTokens,
                                          long maxWaitTimeNanos)

This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

Parameters:

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

maxWaitTimeNanos - limit of time(in nanoseconds) which thread can wait.

Returns:

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

See Also:

tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

tryConsumeUninterruptibly

default boolean tryConsumeUninterruptibly(long numTokens,
                                          Duration maxWait)

This is just overloaded equivalent of tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

Parameters:

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

maxWait - limit of time which thread can wait.

Returns:

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

See Also:

tryConsumeUninterruptibly(long, long, UninterruptibleBlockingStrategy)

consume

void consume(long numTokens,
             BlockingStrategy blockingStrategy)
      throws InterruptedException

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.

Parameters:

numTokens - 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

consume

default void consume(long numTokens)
              throws InterruptedException

This is just overloaded equivalent of consume(long, BlockingStrategy)

Parameters:

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

Throws:

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

See Also:

consume(long, BlockingStrategy)

consumeUninterruptibly

void consumeUninterruptibly(long numTokens,
                            UninterruptibleBlockingStrategy blockingStrategy)

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

Parameters:

numTokens - 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:

consume(long, BlockingStrategy)

consumeUninterruptibly

default void consumeUninterruptibly(long numTokens)

This is just overloaded equivalent of consumeUninterruptibly(long, UninterruptibleBlockingStrategy)

Parameters:

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

See Also:

consumeUninterruptibly(long, UninterruptibleBlockingStrategy)