AsyncBucket (bucket4j-core 6.2.0 API)

```
public interface AsyncBucket
```
Provides asynchronous API for bucket. Any bucket supports the asynchronous mode iff particular Extension behind the bucket provides asynchronous mode.
A special notes about in-memory buckets:: this interface is useless for in-memory buckets because in-memory bucket does not communicate with external back-ends, as result any thread is never blocked by IO operations.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`CompletableFuture<Void>`	`addTokens(long tokensToAdd)` Asynchronous version of `Bucket.addTokens(long)`, follows the same semantic.
`AsyncVerboseBucket`	`asVerbose()` Returns the verbose view of this bucket.
`CompletableFuture<Long>`	`consumeIgnoringRateLimits(long tokens)` Asynchronous version of `Bucket.consumeIgnoringRateLimits(long)`, follows the same semantic.
`CompletableFuture<EstimationProbe>`	`estimateAbilityToConsume(long numTokens)` Asynchronous version of `Bucket.estimateAbilityToConsume(long)`, follows the same semantic.
`CompletableFuture<Void>`	`forceAddTokens(long tokensToAdd)` Asynchronous version of `Bucket.forceAddTokens(long)`, follows the same semantic.
`CompletableFuture<Void>`	`replaceConfiguration(BucketConfiguration newConfiguration, TokensInheritanceStrategy tokensInheritanceStrategy)` Has the same semantic with `Bucket.replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)`
`CompletableFuture<Boolean>`	`tryConsume(long numTokens)` Asynchronous version of `Bucket.tryConsume(long)`, follows the same semantic.
`CompletableFuture<ConsumptionProbe>`	`tryConsumeAndReturnRemaining(long numTokens)` Asynchronous version of `Bucket.tryConsumeAndReturnRemaining(long)`, follows the same semantic.
`CompletableFuture<Long>`	`tryConsumeAsMuchAsPossible()` Asynchronous version of `Bucket.tryConsumeAsMuchAsPossible()`, follows the same semantic.
`CompletableFuture<Long>`	`tryConsumeAsMuchAsPossible(long limit)` Asynchronous version of `Bucket.tryConsumeAsMuchAsPossible(long)`, follows the same semantic.

- Method Detail
  - 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:
    
    Bucket.tryConsume(long)
  - consumeIgnoringRateLimits
```
CompletableFuture<Long> consumeIgnoringRateLimits(long tokens)
```
    Asynchronous version of Bucket.consumeIgnoringRateLimits(long), follows the same semantic.
    
    See Also:
    
    Bucket.consumeIgnoringRateLimits(long)
  - 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:
    
    Bucket.tryConsumeAndReturnRemaining(long)
  - 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:
    
    Bucket.estimateAbilityToConsume(long)
  - 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:
    
    Bucket.tryConsumeAsMuchAsPossible()
  - 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:
    
    Bucket.tryConsumeAsMuchAsPossible(long)
  - 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:
    
    Bucket.addTokens(long)
  - 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:
    
    Bucket.addTokens(long)
  - replaceConfiguration
```
CompletableFuture<Void> replaceConfiguration(BucketConfiguration newConfiguration,
                                             TokensInheritanceStrategy tokensInheritanceStrategy)
```
    Has the same semantic with Bucket.replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)

Interface AsyncBucket

Method Summary

Method Detail

asVerbose

tryConsume

consumeIgnoringRateLimits

tryConsumeAndReturnRemaining

estimateAbilityToConsume

tryConsumeAsMuchAsPossible

tryConsumeAsMuchAsPossible

addTokens

forceAddTokens

replaceConfiguration