io.github.bucket4j.distributed.proxy

Class DefaultAsyncBucketProxy

java.lang.Object

io.github.bucket4j.distributed.proxy.DefaultAsyncBucketProxy

All Implemented Interfaces:

AsyncBucketProxy, ScheduledBucket

public class DefaultAsyncBucketProxy
extends Object
implements AsyncBucketProxy, ScheduledBucket

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	addTokens(long tokensToAdd) Asynchronous version of Bucket.addTokens(long), follows the same semantic.
ScheduledBucket	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<Long>	getAvailableTokens() Returns amount of available tokens in this bucket.
CompletableFuture<Void>	replaceConfiguration(BucketConfiguration newConfiguration) Asynchronous version of Bucket.replaceConfiguration(BucketConfiguration), follows the same rules and semantic.
CompletableFuture<Void>	syncByCondition(long unsynchronizedTokens, Duration timeSinceLastSync) TODO javadocs
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.AsyncBucketProxy

fromSync, syncImmediately

Methods inherited from interface io.github.bucket4j.ScheduledBucket

tryConsume

Constructor Detail

DefaultAsyncBucketProxy

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

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

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 ScheduledBucket

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

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 ScheduledBucket

Parameters:

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

scheduler - used to delayed future completion

replaceConfiguration

public CompletableFuture<Void> replaceConfiguration(BucketConfiguration newConfiguration)

Description copied from interface: AsyncBucketProxy

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.

Specified by:

replaceConfiguration in interface AsyncBucketProxy

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)

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)

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

syncByCondition

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

Description copied from interface: AsyncBucketProxy

TODO javadocs

Specified by:

syncByCondition in interface AsyncBucketProxy

Returns: