io.github.bucket4j.distributed.proxy

Class DefaultAsyncBucketProxy

java.lang.Object

io.github.bucket4j.distributed.proxy.DefaultAsyncBucketProxy

All Implemented Interfaces:

AsyncBucketProxy, AsyncOptimizationController, SchedulingBucket

public class DefaultAsyncBucketProxy
extends Object
implements AsyncBucketProxy, AsyncOptimizationController, SchedulingBucket

Constructor Summary

Constructors

Constructor and Description
DefaultAsyncBucketProxy(AsyncCommandExecutor commandExecutor, RecoveryStrategy recoveryStrategy, Supplier<CompletableFuture<BucketConfiguration>> configurationSupplier, ImplicitConfigurationReplacement implicitConfigurationReplacement)

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	addTokens(long tokensToAdd) Asynchronous version of Bucket.addTokens(long), follows the same semantic.
SchedulingBucket	asScheduler() Returns asynchronous view of this bucket that allows to use bucket as async scheduler.
AsyncVerboseBucket	asVerbose() Returns the verbose view of this bucket.
CompletableFuture<Void>	consume(long tokensToConsume, ScheduledExecutorService scheduler) Consumes the specified number of tokens from the bucket.
CompletableFuture<Long>	consumeIgnoringRateLimits(long tokensToConsume) 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<Long>	getAvailableTokens() Returns amount of available tokens in this bucket.
AsyncOptimizationController	getOptimizationController() Returns optimization controller for this proxy.
CompletableFuture<Void>	replaceConfiguration(BucketConfiguration newConfiguration, TokensInheritanceStrategy tokensInheritanceStrategy) Has the same semantic with Bucket.replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)
CompletableFuture<Void>	reset() Reset all tokens up to maximum capacity.
CompletableFuture<Void>	syncByCondition(long unsynchronizedTokens, Duration timeSinceLastSync) Initiates immediate synchronization of local copy of bucket with remote storage in case of both conditions bellow are true: Accumulated amount of locally consumed tokens without external synchronization is greater than or equal to unsynchronizedTokens Time passed since last synchronization with external storage is greater than or equal to timeSinceLastSync
AsyncBucketProxy	toListenable(BucketListener listener) Returns new copy of this bucket instance decorated by listener.
CompletableFuture<Boolean>	tryConsume(long tokensToConsume) Asynchronous version of Bucket.tryConsume(long), follows the same semantic.
CompletableFuture<Boolean>	tryConsume(long tokensToConsume, long maxWaitTimeNanos, ScheduledExecutorService scheduler) Tries to consume the specified number of tokens from the bucket.
CompletableFuture<ConsumptionProbe>	tryConsumeAndReturnRemaining(long tokensToConsume) 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.github.bucket4j.distributed.AsyncOptimizationController

syncImmediately

Methods inherited from interface io.github.bucket4j.SchedulingBucket

tryConsume

Constructor Detail

DefaultAsyncBucketProxy

public DefaultAsyncBucketProxy(AsyncCommandExecutor commandExecutor,
                               RecoveryStrategy recoveryStrategy,
                               Supplier<CompletableFuture<BucketConfiguration>> configurationSupplier,
                               ImplicitConfigurationReplacement implicitConfigurationReplacement)

Method Detail

asVerbose

public AsyncVerboseBucket asVerbose()

Description copied from interface: AsyncBucketProxy

Returns the verbose view of this bucket.

Specified by:

asVerbose in interface AsyncBucketProxy

toListenable

public AsyncBucketProxy toListenable(BucketListener listener)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

toListenable in interface AsyncBucketProxy

Parameters:

listener - the listener of bucket events.

Returns:

new bucket instance decorated by listener

asScheduler

public SchedulingBucket asScheduler()

Description copied from interface: AsyncBucketProxy

Returns asynchronous view of this bucket that allows to use bucket as async scheduler.

Specified by:

asScheduler in interface AsyncBucketProxy

Returns:

Asynchronous view of this bucket that allows to use bucket as async scheduler.

consumeIgnoringRateLimits

public CompletableFuture<Long> consumeIgnoringRateLimits(long tokensToConsume)

Description copied from interface: AsyncBucketProxy

Asynchronous version of Bucket.consumeIgnoringRateLimits(long), follows the same semantic.

Specified by:

consumeIgnoringRateLimits in interface AsyncBucketProxy

See Also:

Bucket.consumeIgnoringRateLimits(long)

tryConsume

public CompletableFuture<Boolean> tryConsume(long tokensToConsume)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

tryConsume in interface AsyncBucketProxy

Parameters:

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

public CompletableFuture<ConsumptionProbe> tryConsumeAndReturnRemaining(long tokensToConsume)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

tryConsumeAndReturnRemaining in interface AsyncBucketProxy

Parameters:

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

public CompletableFuture<EstimationProbe> estimateAbilityToConsume(long numTokens)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

estimateAbilityToConsume in interface AsyncBucketProxy

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

public CompletableFuture<Long> tryConsumeAsMuchAsPossible()

Description copied from interface: AsyncBucketProxy

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.

Specified by:

tryConsumeAsMuchAsPossible in interface AsyncBucketProxy

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

public CompletableFuture<Long> tryConsumeAsMuchAsPossible(long limit)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

tryConsumeAsMuchAsPossible in interface AsyncBucketProxy

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

public CompletableFuture<Boolean> tryConsume(long tokensToConsume,
                                             long maxWaitTimeNanos,
                                             ScheduledExecutorService scheduler)

Description copied from interface: SchedulingBucket

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

Specified by:

tryConsume in interface SchedulingBucket

Parameters:

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

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

scheduler - used to delayed future completion

consume

public CompletableFuture<Void> consume(long tokensToConsume,
                                       ScheduledExecutorService scheduler)

Description copied from interface: SchedulingBucket

Consumes 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.
  • Else tokens reserved(effectively consumed) and 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.

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

Specified by:

consume in interface SchedulingBucket

Parameters:

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

scheduler - used to delayed future completion

replaceConfiguration

public CompletableFuture<Void> replaceConfiguration(BucketConfiguration newConfiguration,
                                                    TokensInheritanceStrategy tokensInheritanceStrategy)

Description copied from interface: AsyncBucketProxy

Has the same semantic with Bucket.replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)

Specified by:

replaceConfiguration in interface AsyncBucketProxy

addTokens

public CompletableFuture<Void> addTokens(long tokensToAdd)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

addTokens in interface AsyncBucketProxy

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

public CompletableFuture<Void> forceAddTokens(long tokensToAdd)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

forceAddTokens in interface AsyncBucketProxy

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)

reset

public CompletableFuture<Void> reset()

Description copied from interface: AsyncBucketProxy

Reset all tokens up to maximum capacity.

Specified by:

reset in interface AsyncBucketProxy

getAvailableTokens

public CompletableFuture<Long> getAvailableTokens()

Description copied from interface: AsyncBucketProxy

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/multi-process environment.

Specified by:

getAvailableTokens in interface AsyncBucketProxy

Returns:

amount of available tokens

getOptimizationController

public AsyncOptimizationController getOptimizationController()

Description copied from interface: AsyncBucketProxy

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.

Specified by:

getOptimizationController in interface AsyncBucketProxy

Returns:

optimization controller for this proxy

syncByCondition

public CompletableFuture<Void> syncByCondition(long unsynchronizedTokens,
                                               Duration timeSinceLastSync)

Description copied from interface: AsyncOptimizationController

Initiates immediate synchronization of local copy of bucket with remote storage in case of both conditions bellow are true:

• Accumulated amount of locally consumed tokens without external synchronization is greater than or equal to unsynchronizedTokens
• Time passed since last synchronization with external storage is greater than or equal to timeSinceLastSync

Specified by:

syncByCondition in interface AsyncOptimizationController

Parameters:

unsynchronizedTokens - criterion for accumulated amount of unsynchronized tokens

timeSinceLastSync - criterion for time passed since last synchronization

Returns:

future that will be completed when local copy of bucket will be synchronized with remote storage, or immediately completed future in case of this synchronization is not required.