io.github.bucket4j

Interface AsyncBucket

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 local buckets: Majority of methods(excepting tryConsume(long, long, ScheduledExecutorService)) from interface AsyncBucket are useless for local buckets, because local bucket does not communicate with external back-ends, as result any thread is never blocked, thus for local buckets only conditional consuming with timed limit) is the legal use case of asynchronous API.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	addTokens(long tokensToAdd) Asynchronous version of Bucket.addTokens(long), follows the same semantic.
CompletableFuture<Void>	replaceConfiguration(BucketConfiguration newConfiguration) Asynchronous version of Bucket.replaceConfiguration(BucketConfiguration), follows the same rules and semantic.
CompletableFuture<Boolean>	tryConsume(long numTokens) Asynchronous version of Bucket.tryConsume(long), follows the same semantic.
CompletableFuture<Boolean>	tryConsume(long numTokens, long maxWaitNanos, ScheduledExecutorService scheduler) Tries to consume the specified number of tokens from the bucket.
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

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)

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)

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)

tryConsume

CompletableFuture<Boolean> tryConsume(long numTokens,
                                      long maxWaitNanos,
                                      ScheduledExecutorService scheduler)

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

The algorithm for all type of buckets is following:

• Implementation issues asynchronous request to back-end behind the bucket(for local bucket it is just a synchronous call) in way which specific for each particular back-end.
• Then uncompleted future returned to the caller.
• If back-end provides signal(through callback) that asynchronous request failed, then future completed exceptionally.
• When back-end provides signal(through callback) that request is done(for local bucket response got immediately), then following post-processing rules will be applied:
  • If tokens were consumed then future immediately completed by true.
  • If tokens were not consumed because were not enough tokens in the bucket and maxWaitNanos nanoseconds is not enough time to refill deficit, then future immediately completed by false.
  • If tokens were reserved(effectively consumed) then task to delayed completion will be scheduled to the scheduler via ScheduledExecutorService.schedule(Runnable, long, TimeUnit), when delay equals to time required to refill the deficit of tokens. After scheduler executes task the future completed by true.

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).

Returns:

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

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)

replaceConfiguration

CompletableFuture<Void> replaceConfiguration(BucketConfiguration newConfiguration)

Asynchronous version of Bucket.replaceConfiguration(BucketConfiguration), follows the same rules and 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.replaceConfiguration(BucketConfiguration)
• 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:

newConfiguration - new configuration

Returns:

Future which completed normally when reconfiguration done normally. Future will be completed with IncompatibleConfigurationException if new configuration is incompatible with previous.

See Also:

Bucket.replaceConfiguration(BucketConfiguration)