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

Interface AsyncBucketProxy

All Known Implementing Classes:
AsyncBucketProxyAdapter, DefaultAsyncBucketProxy
public interface AsyncBucketProxy
Asynchronous analog of BucketProxy.

  • Method Details

    • asScheduler

      SchedulingBucket asScheduler()
      Returns asynchronous view of this bucket that allows to use bucket as async scheduler.
      Returns:
      Asynchronous view of this bucket that allows to use bucket as async scheduler.

    • asVerbose

      AsyncVerboseBucket asVerbose()
      Returns the verbose view of this bucket.

    • tryConsume

      CompletableFuture<Boolean> tryConsume(long numTokens)
      Asynchronous version of Bucket.tryConsume(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.tryConsume(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      numTokens - The number of tokens to consume from the bucket, must be a positive number.
      Returns:
      the future which eventually will be completed by true if the numTokens were consumed and completed by false otherwise.
      See Also:

    • consumeIgnoringRateLimits

      CompletableFuture<Long> consumeIgnoringRateLimits(long tokens)
      Asynchronous version of Bucket.consumeIgnoringRateLimits(long), follows the same semantic.
      See Also:

    • tryConsumeAndReturnRemaining

      CompletableFuture<ConsumptionProbe> tryConsumeAndReturnRemaining(long numTokens)
      Asynchronous version of Bucket.tryConsumeAndReturnRemaining(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.tryConsumeAndReturnRemaining(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      numTokens - The number of tokens to consume from the bucket, must be a positive number.
      Returns:
      the future which eventually will be completed by probe which describes both result of consumption and tokens remaining in the bucket after consumption.
      See Also:

    • estimateAbilityToConsume

      CompletableFuture<EstimationProbe> estimateAbilityToConsume(long numTokens)
      Asynchronous version of Bucket.estimateAbilityToConsume(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.estimateAbilityToConsume(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      numTokens - The number of tokens to consume from the bucket, must be a positive number.
      Returns:
      the future which eventually will be completed by probe which describes the ability to consume specified amount of tokens.
      See Also:

    • tryConsumeAsMuchAsPossible

      CompletableFuture<Long> tryConsumeAsMuchAsPossible()
      Asynchronous version of Bucket.tryConsumeAsMuchAsPossible(), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.tryConsumeAsMuchAsPossible()
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Returns:
      the future which eventually will be completed by number of tokens which has been consumed, or completed by zero if was consumed nothing.
      See Also:

    • tryConsumeAsMuchAsPossible

      CompletableFuture<Long> tryConsumeAsMuchAsPossible(long limit)
      Asynchronous version of Bucket.tryConsumeAsMuchAsPossible(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.tryConsumeAsMuchAsPossible(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      limit - maximum number of tokens to consume, should be positive.
      Returns:
      the future which eventually will be completed by number of tokens which has been consumed, or completed by zero if was consumed nothing.
      See Also:

    • addTokens

      CompletableFuture<Void> addTokens(long tokensToAdd)
      Asynchronous version of Bucket.addTokens(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.addTokens(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      tokensToAdd - number of tokens to add
      Returns:
      the future which eventually will be completed by null if operation successfully completed without exception, otherwise(if any exception happen in asynchronous flow) the future will be completed exceptionally.
      See Also:

    • forceAddTokens

      CompletableFuture<Void> forceAddTokens(long tokensToAdd)
      Asynchronous version of Bucket.forceAddTokens(long), follows the same semantic.

      The algorithm for distribute buckets is following:

      • Implementation issues asynchronous request to back-end behind the bucket in way which specific for each particular back-end.
      • Then uncompleted future returned to the caller.
      • When back-end provides signal(through callback) that request is done, then future completed.
      • If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
      It is strongly not recommended to do any heavy work in thread which completes the future, because typically this will be a back-end thread which handles NIO selectors, blocking this thread will take negative performance effect to back-end throughput, so you always should resume control flow in another executor via methods like CompletableFuture.thenApplyAsync(Function, Executor).

      The algorithm for local buckets is following:

      • Implementation just redirects request to synchronous version Bucket.addTokens(long)
      • Then returns feature immediately completed by results from previous step. So using this method for local buckets is useless, because there are no differences with synchronous version.
      Parameters:
      tokensToAdd - number of tokens to add
      Returns:
      the future which eventually will be completed by null if operation successfully completed without exception, otherwise(if any exception happen in asynchronous flow) the future will be completed exceptionally.
      See Also:

    • reset

      CompletableFuture<Void> reset()
      Reset all tokens up to maximum capacity.

    • replaceConfiguration

      CompletableFuture<Void> replaceConfiguration(BucketConfiguration newConfiguration, TokensInheritanceStrategy tokensInheritanceStrategy)
      Has the same semantic with Bucket.replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)

    • toListenable

      AsyncBucketProxy toListenable(BucketListener listener)
      Returns new copy of this bucket instance decorated by listener. The created bucket will share same tokens with source bucket and vice versa.

      See javadocs for BucketListener in order to understand semantic of listener.

      Parameters:
      listener - the listener of bucket events.
      Returns:
      new bucket instance decorated by listener

    • getAvailableTokens

      CompletableFuture<Long> getAvailableTokens()
      Returns amount of available tokens in this bucket.

      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/multiprocess environment.

      Returns:
      amount of available tokens

    • getOptimizationController

      AsyncOptimizationController getOptimizationController()
      Returns optimization controller for this proxy.

      This method is actual only if an optimization was applied during bucket construction via RemoteAsyncBucketBuilder.withOptimization(Optimization) otherwise returned controller will do nothing.

      Returns:
      optimization controller for this proxy