org.threadly.concurrent.wrapper.limiter

Class KeyedSubmitterSchedulerLimiter

java.lang.Object

org.threadly.concurrent.wrapper.limiter.KeyedSubmitterSchedulerLimiter

public class KeyedSubmitterSchedulerLimiter
extends java.lang.Object

This is a cross between the KeyDistributedScheduler and a SubmitterSchedulerLimiter. This is designed to limit concurrency for a given thread, but permit more than one thread to run at a time for a given key. If the desired effect is to have a single thread per key, KeyDistributedScheduler is a much better option.

The easiest way to use this class would be to have it distribute out schedulers through getSubmitterSchedulerForKey(Object).

Since:

4.6.0 (since 4.3.0 at org.threadly.concurrent.limiter)

Constructor Summary

Constructors

Constructor and Description
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency) Construct a new KeyedSubmitterSchedulerLimiter providing only the backing scheduler and the maximum concurrency per unique key.
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency, boolean limitFutureListenersExecution) Construct a new KeyedSubmitterSchedulerLimiter providing only the backing scheduler and the maximum concurrency per unique key.
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency, java.lang.String subPoolName, boolean addKeyToThreadName) Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency, java.lang.String subPoolName, boolean addKeyToThreadName, boolean limitFutureListenersExecution) Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency, java.lang.String subPoolName, boolean addKeyToThreadName, boolean limitFutureListenersExecution, int expectedParallism) Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.
KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler, int maxConcurrency, java.lang.String subPoolName, boolean addKeyToThreadName, int expectedParallism) Deprecated. Please use construct by specifying limitFutureListenersExecution

Method Summary

Modifier and Type	Method and Description
void	execute(java.lang.Object taskKey, java.lang.Runnable task) Provide a task to be run with a given thread key.
int	getMaxConcurrencyPerKey() Check how many threads may run in parallel for a single unique key.
SubmitterExecutor	getSubmitterExecutorForKey(java.lang.Object taskKey) Returns an executor implementation where all tasks submitted on this executor will run on the provided key.
SubmitterScheduler	getSubmitterSchedulerForKey(java.lang.Object taskKey) Returns a scheduler implementation where all tasks submitted on this scheduler will run on the provided key.
int	getTrackedKeyCount() Check how many keys are currently being restricted or monitored.
int	getUnsubmittedTaskCount(java.lang.Object taskKey) Check how many tasks are currently being limited, and not submitted yet for a given key.
java.util.Map<java.lang.Object,java.lang.Integer>	getUnsubmittedTaskCountMap() Get a map of all the keys and how many tasks are held back (queued) in each limiter per key.
void	schedule(java.lang.Object taskKey, java.lang.Runnable task, long delayInMs) Schedule a one time task with a given delay.
void	scheduleAtFixedRate(java.lang.Object taskKey, java.lang.Runnable task, long initialDelay, long period) Schedule a fixed rate recurring task to run.
void	scheduleWithFixedDelay(java.lang.Object taskKey, java.lang.Runnable task, long initialDelay, long recurringDelay) Schedule a fixed delay recurring task to run.
void	setMaxConcurrencyPerKey(int maxConcurrency) Updates the concurrency limit for each key.
<TT> ListenableFuture<TT>	submit(java.lang.Object taskKey, java.util.concurrent.Callable<TT> 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.
<TT> ListenableFuture<TT>	submit(java.lang.Object taskKey, java.lang.Runnable task, TT result) Submit a task to be run with a given thread key.
<TT> ListenableFuture<TT>	submitScheduled(java.lang.Object taskKey, java.util.concurrent.Callable<TT> task, long delayInMs) Schedule a Callable with a given delay.
ListenableFuture<?>	submitScheduled(java.lang.Object taskKey, java.lang.Runnable task, long delayInMs) Schedule a task with a given delay.
<TT> ListenableFuture<TT>	submitScheduled(java.lang.Object taskKey, java.lang.Runnable task, TT result, long delayInMs) Schedule a task with a given delay.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyedSubmitterSchedulerLimiter

public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                      int maxConcurrency)

Construct a new KeyedSubmitterSchedulerLimiter providing only the backing scheduler and the maximum concurrency per unique key. By default this will not rename threads for tasks executing.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

KeyedSubmitterSchedulerLimiter

public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                      int maxConcurrency,
                                      boolean limitFutureListenersExecution)

Construct a new KeyedSubmitterSchedulerLimiter providing only the backing scheduler and the maximum concurrency per unique key. By default this will not rename threads for tasks executing.

This constructor allows you to specify if listeners / FutureCallback's / functions in ListenableFuture.map(java.util.function.Function) or ListenableFuture.flatMap(java.util.function.Function) should be counted towards the concurrency limit. Specifying false will release the limit as soon as the original task completes. Specifying true will continue to enforce the limit until all listeners (without an executor) complete.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

limitFutureListenersExecution - true to include listener / mapped functions towards execution limit

KeyedSubmitterSchedulerLimiter

public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                      int maxConcurrency,
                                      java.lang.String subPoolName,
                                      boolean addKeyToThreadName)

Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

subPoolName - Name prefix for sub pools, null to not change thread names

addKeyToThreadName - If true the key's .toString() will be added in the thread name

KeyedSubmitterSchedulerLimiter

public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                      int maxConcurrency,
                                      java.lang.String subPoolName,
                                      boolean addKeyToThreadName,
                                      boolean limitFutureListenersExecution)

Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.

This constructor allows you to specify if listeners / FutureCallback's / functions in ListenableFuture.map(java.util.function.Function) or ListenableFuture.flatMap(java.util.function.Function) should be counted towards the concurrency limit. Specifying false will release the limit as soon as the original task completes. Specifying true will continue to enforce the limit until all listeners (without an executor) complete.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

subPoolName - Name prefix for sub pools, null to not change thread names

addKeyToThreadName - If true the key's .toString() will be added in the thread name

limitFutureListenersExecution - true to include listener / mapped functions towards execution limit

KeyedSubmitterSchedulerLimiter

@Deprecated
public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                                  int maxConcurrency,
                                                  java.lang.String subPoolName,
                                                  boolean addKeyToThreadName,
                                                  int expectedParallism)

Deprecated. Please use construct by specifying limitFutureListenersExecution

Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.

The parallelism value should be a factor of how many keys are submitted to the pool during any given period of time. Depending on task execution duration, and quantity of threads executing tasks this value may be able to be smaller than expected. Higher values result in less lock contention, but more memory usage. Most systems will run fine with this anywhere from 4 to 64.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

subPoolName - Name prefix for sub pools, null to not change thread names

addKeyToThreadName - If true the key's .toString() will be added in the thread name

expectedParallism - Expected concurrent task addition access, used for performance tuning

KeyedSubmitterSchedulerLimiter

public KeyedSubmitterSchedulerLimiter(SubmitterScheduler scheduler,
                                      int maxConcurrency,
                                      java.lang.String subPoolName,
                                      boolean addKeyToThreadName,
                                      boolean limitFutureListenersExecution,
                                      int expectedParallism)

Construct a new KeyedSubmitterSchedulerLimiter providing the backing scheduler, the maximum concurrency per unique key, and how keyed limiter threads should be named.

The parallelism value should be a factor of how many keys are submitted to the pool during any given period of time. Depending on task execution duration, and quantity of threads executing tasks this value may be able to be smaller than expected. Higher values result in less lock contention, but more memory usage. Most systems will run fine with this anywhere from 4 to 64.

This constructor allows you to specify if listeners / FutureCallback's / functions in ListenableFuture.map(java.util.function.Function) or ListenableFuture.flatMap(java.util.function.Function) should be counted towards the concurrency limit. Specifying false will release the limit as soon as the original task completes. Specifying true will continue to enforce the limit until all listeners (without an executor) complete.

Parameters:

scheduler - Scheduler to execute and schedule tasks on

maxConcurrency - Maximum concurrency allowed per task key

subPoolName - Name prefix for sub pools, null to not change thread names

addKeyToThreadName - If true the key's .toString() will be added in the thread name

limitFutureListenersExecution - true to include listener / mapped functions towards execution limit

expectedParallism - Expected concurrent task addition access, used for performance tuning

Method Detail

submitScheduled

public ListenableFuture<?> submitScheduled(java.lang.Object taskKey,
                                           java.lang.Runnable task,
                                           long delayInMs)

Schedule a task with a given delay. There is a slight increase in load when using submitScheduled(Object, Runnable, long) over schedule(Object, Runnable, long). So this should only be used when the future is necessary.

The Future.get() method will return null once the runnable has completed.

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.submitScheduled(Runnable, long)

Parameters:

taskKey - Key to use for identifying execution limit

task - runnable to execute

delayInMs - time in milliseconds to wait to execute task

Returns:

a future to know when the task has completed

submitScheduled

public <TT> ListenableFuture<TT> submitScheduled(java.lang.Object taskKey,
                                                 java.lang.Runnable task,
                                                 TT result,
                                                 long delayInMs)

Schedule a task with a given delay. The Future.get() method will return the provided result once the runnable has completed.

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.submitScheduled(Runnable, Object, long)

Type Parameters:

TT - type of result returned from the future

Parameters:

taskKey - Key to use for identifying execution limit

task - runnable to execute

result - result to be returned from resulting future .get() when runnable completes

delayInMs - time in milliseconds to wait to execute task

Returns:

a future to know when the task has completed

submitScheduled

public <TT> ListenableFuture<TT> submitScheduled(java.lang.Object taskKey,
                                                 java.util.concurrent.Callable<TT> task,
                                                 long delayInMs)

Schedule a Callable with a given delay. This is needed when a result needs to be consumed from the callable.

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.submitScheduled(Callable, long)

Type Parameters:

TT - type of result returned from the future

Parameters:

taskKey - Key to use for identifying execution limit

task - callable to be executed

delayInMs - time in milliseconds to wait to execute task

Returns:

a future to know when the task has completed and get the result of the callable

schedule

public void schedule(java.lang.Object taskKey,
                     java.lang.Runnable task,
                     long delayInMs)

Schedule a one time task with a given delay.

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.schedule(Runnable, long)

Parameters:

taskKey - Key to use for identifying execution limit

task - runnable to execute

delayInMs - time in milliseconds to wait to execute task

scheduleWithFixedDelay

public void scheduleWithFixedDelay(java.lang.Object taskKey,
                                   java.lang.Runnable task,
                                   long initialDelay,
                                   long recurringDelay)

Schedule a fixed delay recurring task to run. The recurring delay time will be from the point where execution has finished. So the execution frequency is the recurringDelay + runtime for the provided task.

Unlike ScheduledExecutorService if the task throws an exception, subsequent executions are NOT suppressed or prevented. So if the task throws an exception on every run, the task will continue to be executed at the provided recurring delay (possibly throwing an exception on each execution).

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.scheduleWithFixedDelay(Runnable, long, long)

Parameters:

taskKey - Key to use for identifying execution limit

task - runnable to be executed

initialDelay - delay in milliseconds until first run

recurringDelay - delay in milliseconds for running task after last finish

scheduleAtFixedRate

public void scheduleAtFixedRate(java.lang.Object taskKey,
                                java.lang.Runnable task,
                                long initialDelay,
                                long period)

Schedule a fixed rate recurring task to run. The recurring delay will be the same, regardless of how long task execution takes. A given runnable will not run concurrently (unless it is submitted to the scheduler multiple times). Instead of execution takes longer than the period, the next run will occur immediately (given thread availability in the pool).

Unlike ScheduledExecutorService if the task throws an exception, subsequent executions are NOT suppressed or prevented. So if the task throws an exception on every run, the task will continue to be executed at the provided recurring delay (possibly throwing an exception on each execution).

The key is used to identify this threads execution limit. Tasks with matching keys will be limited concurrent execution to the level returned by getMaxConcurrencyPerKey().

See also: SubmitterScheduler.scheduleAtFixedRate(Runnable, long, long)

Parameters:

taskKey - Key to use for identifying execution limit

task - runnable to be executed

initialDelay - delay in milliseconds until first run

period - amount of time in milliseconds between the start of recurring executions

getSubmitterSchedulerForKey

public SubmitterScheduler getSubmitterSchedulerForKey(java.lang.Object taskKey)

Returns a scheduler implementation where all tasks submitted on this scheduler 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:

scheduler which will only execute with reference to the provided key

getMaxConcurrencyPerKey

public int getMaxConcurrencyPerKey()

Check how many threads may run in parallel for a single unique key.

Returns:

maximum concurrent tasks to be run per key

setMaxConcurrencyPerKey

public void setMaxConcurrencyPerKey(int maxConcurrency)

Updates the concurrency limit for each key. If reducing the the limit, there will be no attempt or impact on tasks already limiting. Instead new tasks just wont be submitted to the parent pool until existing tasks complete and go below the new limit.

Parameters:

maxConcurrency - maximum quantity of tasks to run in parallel per key

Since:

5.4

getTrackedKeyCount

public int getTrackedKeyCount()

Check how many keys are currently being restricted or monitored.

Returns:

The number of task keys being monitored

getUnsubmittedTaskCount

public int getUnsubmittedTaskCount(java.lang.Object taskKey)

Check how many tasks are currently being limited, and not submitted yet for a given key. This can be useful for knowing how backed up a specific key is.

Parameters:

taskKey - Key which would be limited

Returns:

Quantity of tasks being held back inside the limiter, and thus still queued

getUnsubmittedTaskCountMap

public java.util.Map<java.lang.Object,java.lang.Integer> getUnsubmittedTaskCountMap()

Get a map of all the keys and how many tasks are held back (queued) in each limiter per key. This map is generated without locking. Due to that, this may be inaccurate as task queue sizes changed while iterating all key's limiters.

Because this requires an iteration of all limiters, if only a single limiters unsubmitted count is needed, use getUnsubmittedTaskCount(Object) as a cheaper alternative.

Returns:

Map of task key's to their respective task queue size

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)

Parameters:

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

task - Task to be executed

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)

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 <TT> ListenableFuture<TT> submit(java.lang.Object taskKey,
                                        java.lang.Runnable task,
                                        TT result)

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

See also: SubmitterExecutor.submit(Runnable, Object)

Type Parameters:

TT - 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 <TT> ListenableFuture<TT> submit(java.lang.Object taskKey,
                                        java.util.concurrent.Callable<TT> task)

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

See also: SubmitterExecutor.submit(Callable)

Type Parameters:

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

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