Module io.github.bucket4j.core

Package io.github.bucket4j

Interface SchedulingBucket

All Known Implementing Classes:

AbstractBucket, DefaultAsyncBucketProxy, DefaultBucketProxy, LockFreeBucket, SynchronizedBucket, ThreadUnsafeBucket

public interface SchedulingBucket

Provides the scheduling API for Bucket. Any method of this interface can delay user operation via ScheduledExecutorService in case of lack of tokens.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	consume(long numTokens, ScheduledExecutorService scheduler)	Consumes the specified number of tokens from the bucket.
CompletableFuture<Boolean>	tryConsume(long numTokens, long maxWaitNanos, ScheduledExecutorService scheduler)	Tries to consume the specified number of tokens from the bucket.
default CompletableFuture<Boolean>	tryConsume(long numTokens, Duration maxWait, ScheduledExecutorService scheduler)	This is just overloaded equivalent of tryConsume(long, long, ScheduledExecutorService)

Method Detail

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

Parameters:

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

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

scheduler - used to delayed future completion

tryConsume

default CompletableFuture<Boolean> tryConsume(long numTokens,
                                              Duration maxWait,
                                              ScheduledExecutorService scheduler)

This is just overloaded equivalent of tryConsume(long, long, ScheduledExecutorService)

Parameters:

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

maxWait - limit of time which thread can wait.

scheduler - used to delayed future completion

See Also:

tryConsume(long, long, ScheduledExecutorService)

consume

CompletableFuture<Void> consume(long numTokens,
                                ScheduledExecutorService scheduler)

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

Parameters:

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

scheduler - used to delayed future completion