org.threadly.concurrent.wrapper.limiter

Class KeyedRateLimiterExecutor

java.lang.Object

org.threadly.concurrent.wrapper.limiter.KeyedRateLimiterExecutor

public class KeyedRateLimiterExecutor
extends java.lang.Object

Similar to RateLimiterExecutor except that the rate is applied on a per key basis. Tasks submitted to this executor must all be associated to a key. The key is compared by using Object.hashCode() and Object.equals(Object). For any given key, a rate is applied, but keys which don't match with the above checks will not impact each other.

Because different keys don't interact, this is not capable of providing a global rate limit (unless the key quantity is known and restricted).

This differs from KeyedExecutorLimiter in that while that limits concurrency, this limits by rate (thus there may be periods where nothing is execution, or if executions are long things may run concurrently). Please see RateLimiterExecutor for more details about how rate is limited.

Since:

4.7.0

Constructor Summary

Constructors

Constructor and Description
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond) Constructs a new key rate limiting executor.
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond, long maxScheduleDelayMillis) Constructs a new key rate limiting executor.
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond, long maxScheduleDelayMillis, RejectedExecutionHandler rejectedExecutionHandler) Constructs a new key rate limiting executor.
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond, long maxScheduleDelayMillis, RejectedExecutionHandler rejectedExecutionHandler, java.lang.String subPoolName, boolean addKeyToThreadName) Constructs a new key rate limiting executor.
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond, long maxScheduleDelayMillis, java.lang.String subPoolName, boolean addKeyToThreadName) Constructs a new key rate limiting executor.
KeyedRateLimiterExecutor(SubmitterScheduler scheduler, double permitsPerSecond, java.lang.String subPoolName, boolean addKeyToThreadName) Constructs a new key rate limiting executor.

Method Summary

Modifier and Type	Method and Description
long	execute(double permits, java.lang.Object taskKey, java.lang.Runnable task) Provide a task to be run with a given thread key.
void	execute(java.lang.Object taskKey, java.lang.Runnable task) Provide a task to be run with a given thread key.
ListenableFuture<?>	getFutureTillDelay(java.lang.Object taskKey, long maximumDelay) In order to help assist with avoiding to schedule too much on the scheduler at any given time, this call returns a future that will block until the delay for the next task falls below the maximum delay provided into this call.
int	getMinimumDelay(java.lang.Object taskKey) This call will check how far out we have already scheduled tasks to be run.
SubmitterExecutor	getSubmitterExecutorForKey(double permits, java.lang.Object taskKey) Returns an executor implementation where all tasks submitted on this executor will run on the provided key.
SubmitterExecutor	getSubmitterExecutorForKey(java.lang.Object taskKey) Returns an executor implementation where all tasks submitted on this executor will run on the provided key.
int	getTrackedKeyCount() Check how many keys are currently being restricted or monitored.
<T> ListenableFuture<T>	submit(double permits, java.lang.Object taskKey, java.util.concurrent.Callable<T> task) Submit a callable to be run with a given thread key.
ListenableFuture<?>	submit(double permits, java.lang.Object taskKey, java.lang.Runnable task) Submit a task to be run with a given thread key.
<T> ListenableFuture<T>	submit(double permits, java.lang.Object taskKey, java.lang.Runnable task, T result) Submit a task to be run with a given thread key.
<T> ListenableFuture<T>	submit(java.lang.Object taskKey, java.util.concurrent.Callable<T> task) Submit a callable to be run with a given thread key.
ListenableFuture<?>	submit(java.lang.Object taskKey, java.lang.Runnable task) Submit a task to be run with a given thread key.
<T> ListenableFuture<T>	submit(java.lang.Object taskKey, java.lang.Runnable task, T result) Submit a task to be run with a given thread key.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond)

Constructs a new key rate limiting executor. Using sensible default options.

This will schedule tasks out infinitely far in order to maintain rate. If you want tasks to be rejected at a certain point consider using KeyedRateLimiterExecutor(SubmitterScheduler, double, long).

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond,
                                java.lang.String subPoolName,
                                boolean addKeyToThreadName)

Constructs a new key rate limiting executor. Allowing the specification of thread naming behavior. Providing null or empty for the subPoolName and false for appending the key to the thread name will result in no thread name adjustments occurring.

This will schedule tasks out infinitely far in order to maintain rate. If you want tasks to be rejected at a certain point consider using KeyedRateLimiterExecutor(SubmitterScheduler, double, long, String, boolean).

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

subPoolName - Prefix to give threads while executing tasks submitted through this limiter

addKeyToThreadName - true to append the task's key to the thread name

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond,
                                long maxScheduleDelayMillis)

Constructs a new key rate limiting executor.

This constructor accepts a maximum schedule delay. If a task requires being scheduled out beyond this delay, then a RejectedExecutionException will be thrown instead of scheduling the task.

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

maxScheduleDelayMillis - Maximum amount of time delay tasks in order to maintain rate

Since:

4.8.0

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond,
                                long maxScheduleDelayMillis,
                                RejectedExecutionHandler rejectedExecutionHandler)

Constructs a new key rate limiting executor.

This constructor accepts a maximum schedule delay. If a task requires being scheduled out beyond this delay, then a RejectedExecutionException will be thrown instead of scheduling the task.

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

maxScheduleDelayMillis - Maximum amount of time delay tasks in order to maintain rate

rejectedExecutionHandler - Handler to accept tasks which could not be executed

Since:

4.8.0

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond,
                                long maxScheduleDelayMillis,
                                java.lang.String subPoolName,
                                boolean addKeyToThreadName)

Constructs a new key rate limiting executor. Allowing the specification of thread naming behavior. Providing null or empty for the subPoolName and false for appending the key to the thread name will result in no thread name adjustments occurring.

This constructor accepts a maximum schedule delay. If a task requires being scheduled out beyond this delay, then a RejectedExecutionException will be thrown instead of scheduling the task.

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

maxScheduleDelayMillis - Maximum amount of time delay tasks in order to maintain rate

subPoolName - Prefix to give threads while executing tasks submitted through this limiter

addKeyToThreadName - true to append the task's key to the thread name

Since:

4.8.0

KeyedRateLimiterExecutor

public KeyedRateLimiterExecutor(SubmitterScheduler scheduler,
                                double permitsPerSecond,
                                long maxScheduleDelayMillis,
                                RejectedExecutionHandler rejectedExecutionHandler,
                                java.lang.String subPoolName,
                                boolean addKeyToThreadName)

Constructs a new key rate limiting executor. Allowing the specification of thread naming behavior. Providing null or empty for the subPoolName and false for appending the key to the thread name will result in no thread name adjustments occurring.

This constructor accepts a maximum schedule delay. If a task requires being scheduled out beyond this delay, then a RejectedExecutionException will be thrown instead of scheduling the task.

Parameters:

scheduler - Scheduler to defer executions to

permitsPerSecond - how many permits should be allowed per second per key

maxScheduleDelayMillis - Maximum amount of time delay tasks in order to maintain rate

rejectedExecutionHandler - Handler to accept tasks which could not be executed

subPoolName - Prefix to give threads while executing tasks submitted through this limiter

addKeyToThreadName - true to append the task's key to the thread name

Since:

4.8.0

Method Detail

getTrackedKeyCount

public int getTrackedKeyCount()

Check how many keys are currently being restricted or monitored. This number is particularly relevant for when checking the queued tasks of the parent scheduler. As part of the inner workings of this limiter, a task will exist for each key. Because of that there will be queued tasks which are not actual application submitted work units.

Returns:

The number of task keys being monitored

getMinimumDelay

public int getMinimumDelay(java.lang.Object taskKey)

This call will check how far out we have already scheduled tasks to be run. Because it is the applications responsibility to not provide tasks too fast for the limiter to run them, this can give an idea of how backed up tasks provided through this limiter actually are.

Parameters:

taskKey - object key where equals() will be used to determine execution thread

Returns:

minimum delay in milliseconds for the next task to be provided

getFutureTillDelay

public ListenableFuture<?> getFutureTillDelay(java.lang.Object taskKey,
                                              long maximumDelay)

In order to help assist with avoiding to schedule too much on the scheduler at any given time, this call returns a future that will block until the delay for the next task falls below the maximum delay provided into this call. If you want to ensure that the next task will execute immediately, you should provide a zero to this function. If more tasks are added to the limiter after this call, it will NOT impact when this future will unblock. So this future is assuming that nothing else is added to the limiter after requested.

Parameters:

taskKey - object key where equals() will be used to determine execution thread

maximumDelay - maximum delay in milliseconds until returned Future should unblock

Returns:

Future that will unblock get() calls once delay has been reduced below the provided maximum

execute

public void execute(java.lang.Object taskKey,
                    java.lang.Runnable task)

Provide a task to be run with a given thread key.

See also: Executor.execute(Runnable) and RateLimiterExecutor.execute(Runnable).

Parameters:

taskKey - object key where equals() will be used to determine execution thread

task - Task to be executed

execute

public long execute(double permits,
                    java.lang.Object taskKey,
                    java.lang.Runnable task)

Provide a task to be run with a given thread key.

See also: Executor.execute(Runnable) and RateLimiterExecutor.execute(double, Runnable).

Parameters:

permits - resource permits for this task

taskKey - object key where equals() will be used to determine execution thread

task - Task to be executed

Returns:

Time in milliseconds task was delayed to maintain rate, or -1 if rejected but handler did not throw

submit

public ListenableFuture<?> submit(java.lang.Object taskKey,
                                  java.lang.Runnable task)

Submit a task to be run with a given thread key.

See also: SubmitterExecutor.submit(Runnable) and SubmitterExecutor.submit(Runnable).

Parameters:

taskKey - object key where equals() will be used to determine execution thread

task - Task to be executed

Returns:

Future to represent when the execution has occurred

submit

public ListenableFuture<?> submit(double permits,
                                  java.lang.Object taskKey,
                                  java.lang.Runnable task)

Submit a task to be run with a given thread key.

See also: SubmitterExecutor.submit(Runnable) and RateLimiterExecutor.submit(double, Runnable).

Parameters:

permits - resource permits for this task

taskKey - object key where equals() will be used to determine execution thread

task - Task to be executed

Returns:

Future to represent when the execution has occurred

submit

public <T> ListenableFuture<T> submit(java.lang.Object taskKey,
                                      java.lang.Runnable task,
                                      T result)

Submit a task to be run with a given thread key.

See also: SubmitterExecutor.submit(Runnable, Object) and RateLimiterExecutor.submit(Runnable, Object).

Type Parameters:

T - type of result returned from the future

Parameters:

taskKey - object key where equals() will be used to determine execution thread

task - Runnable to be executed

result - Result to be returned from future when task completes

Returns:

Future to represent when the execution has occurred and provide the given result

submit

public <T> ListenableFuture<T> submit(double permits,
                                      java.lang.Object taskKey,
                                      java.lang.Runnable task,
                                      T result)

Submit a task to be run with a given thread key.

See also: SubmitterExecutor.submit(Runnable, Object) and RateLimiterExecutor.submit(double, Runnable, Object).

Type Parameters:

T - type of result returned from the future

Parameters:

permits - resource permits for this task

taskKey - object key where equals() will be used to determine execution thread

task - Runnable to be executed

result - Result to be returned from future when task completes

Returns:

Future to represent when the execution has occurred and provide the given result

submit

public <T> ListenableFuture<T> submit(java.lang.Object taskKey,
                                      java.util.concurrent.Callable<T> task)

Submit a callable to be run with a given thread key.

See also: SubmitterExecutor.submit(Callable) and RateLimiterExecutor.submit(Callable).

Type Parameters:

T - type of result returned from the future

Parameters:

taskKey - object key where equals() will be used to determine execution thread

task - Callable to be executed

Returns:

Future to represent when the execution has occurred and provide the result from the callable

submit

public <T> ListenableFuture<T> submit(double permits,
                                      java.lang.Object taskKey,
                                      java.util.concurrent.Callable<T> task)

Submit a callable to be run with a given thread key.

See also: SubmitterExecutor.submit(Callable) and RateLimiterExecutor.submit(double, Callable).

Type Parameters:

T - type of result returned from the future

Parameters:

permits - resource permits for this task

taskKey - object key where equals() will be used to determine execution thread

task - Callable to be executed

Returns:

Future to represent when the execution has occurred and provide the result from the callable

getSubmitterExecutorForKey

public SubmitterExecutor getSubmitterExecutorForKey(java.lang.Object taskKey)

Returns an executor implementation where all tasks submitted on this executor will run on the provided key. Tasks executed on the returned scheduler will be limited by the key submitted on this instance equally with ones provided through the returned instance.

Parameters:

taskKey - object key where equals() will be used to determine execution thread

Returns:

Executor which will only execute with reference to the provided key

getSubmitterExecutorForKey

public SubmitterExecutor getSubmitterExecutorForKey(double permits,
                                                    java.lang.Object taskKey)

Returns an executor implementation where all tasks submitted on this executor will run on the provided key. Tasks executed on the returned scheduler will be limited by the key submitted on this instance equally with ones provided through the returned instance.

Parameters:

permits - resource permits for all tasks submitted on the returned executor

taskKey - object key where equals() will be used to determine execution thread

Returns:

Executor which will only execute with reference to the provided key