Module io.github.bucket4j.core
Package io.github.bucket4j

Interface BlockingBucket

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

  • Method Details

    • 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

      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

      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:

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

    • 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

      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

      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:

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

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

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

    • asVerbose

      VerboseBlockingBucket asVerbose()
      Returns the verbose API for this bucket.
      Returns:
      the verbose API for this bucket.