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

Class AsyncBucketProxyAdapter

    • Constructor Detail

      • AsyncBucketProxyAdapter

        public AsyncBucketProxyAdapter​(Bucket target)

    • Method Detail

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

      • tryConsume

        public CompletableFuture<Boolean> tryConsume​(long numTokens)
        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:
        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

        public CompletableFuture<ConsumptionProbe> tryConsumeAndReturnRemaining​(long numTokens)
        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:
        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

        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)

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

      • 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

      • syncImmediately

        public CompletableFuture<Void> syncImmediately()
        Description copied from interface: AsyncOptimizationController
        Initiates immediate synchronization of local copy of bucket with remote storage
        Specified by:
        syncImmediately in interface AsyncOptimizationController
        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.

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

      • 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