org.threadly.concurrent.wrapper

Class KeyDistributedScheduler

java.lang.Object

org.threadly.concurrent.wrapper.KeyDistributedExecutor

org.threadly.concurrent.wrapper.KeyDistributedScheduler

public class KeyDistributedScheduler
extends KeyDistributedExecutor

This is a class which is more full featured than KeyDistributedExecutor, but it does require a scheduler implementation in order to be able to perform scheduling.

The same guarantees and restrictions for the KeyDistributedExecutor also exist for this class. Please read the javadoc for KeyDistributedExecutor to understand more about how this operates.

Since:

4.6.0 (since 1.0.0 as org.threadly.concurrent.TaskSchedulerDistributor)

Constructor Summary

Constructors

Constructor and Description
KeyDistributedScheduler(int expectedParallism, SubmitterScheduler scheduler) Constructor to use a provided scheduler implementation for running tasks.
KeyDistributedScheduler(int expectedParallism, SubmitterScheduler scheduler, boolean accurateQueueSize) Constructor to use a provided scheduler implementation for running tasks.
KeyDistributedScheduler(int expectedParallism, SubmitterScheduler scheduler, int maxTasksPerCycle) Constructor to use a provided scheduler implementation for running tasks.
KeyDistributedScheduler(int expectedParallism, SubmitterScheduler scheduler, int maxTasksPerCycle, boolean accurateQueueSize) Constructor to use a provided scheduler implementation for running tasks.
KeyDistributedScheduler(SubmitterScheduler scheduler) Constructor to use a provided scheduler implementation for running tasks.
KeyDistributedScheduler(SubmitterScheduler scheduler, boolean accurateQueueSize) Constructor to use a provided executor implementation for running tasks.
KeyDistributedScheduler(SubmitterScheduler scheduler, int maxTasksPerCycle) Constructor to use a provided executor implementation for running tasks.
KeyDistributedScheduler(SubmitterScheduler scheduler, int maxTasksPerCycle, boolean accurateQueueSize) Constructor to use a provided executor implementation for running tasks.

Method Summary

Modifier and Type	Method and Description
SubmitterScheduler	getSchedulerForKey(java.lang.Object threadKey) Returns a scheduler implementation where all tasks submitted on this scheduler will run on the provided key.
void	schedule(java.lang.Object threadKey, java.lang.Runnable task, long delayInMs) Schedule a one time task with a given delay that will not run concurrently based off the thread key.
void	scheduleTaskAtFixedRate(java.lang.Object threadKey, java.lang.Runnable task, long initialDelay, long period) Schedule a fixed rate recurring task to run.
void	scheduleTaskWithFixedDelay(java.lang.Object threadKey, java.lang.Runnable task, long initialDelay, long recurringDelay) Schedule a fixed delay recurring task to run.
<T> ListenableFuture<T>	submitScheduled(java.lang.Object threadKey, java.util.concurrent.Callable<T> task, long delayInMs) Schedule a Callable with a given delay.
ListenableFuture<?>	submitScheduled(java.lang.Object threadKey, java.lang.Runnable task, long delayInMs) Schedule a task with a given delay.
<T> ListenableFuture<T>	submitScheduled(java.lang.Object threadKey, java.lang.Runnable task, T result, long delayInMs) Schedule a task with a given delay.

Methods inherited from class org.threadly.concurrent.wrapper.KeyDistributedExecutor

execute, getExecutor, getExecutorForKey, getTaskQueueSize, getTaskQueueSizeMap, submit, submit, submit

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyDistributedScheduler

public KeyDistributedScheduler(SubmitterScheduler scheduler)

Constructor to use a provided scheduler implementation for running tasks.

This constructs with a default expected level of concurrency of 16. This also does not attempt to have an accurate queue size for the KeyDistributedExecutor.getTaskQueueSize(Object) call (thus preferring high performance).

Parameters:

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

KeyDistributedScheduler

public KeyDistributedScheduler(SubmitterScheduler scheduler,
                               boolean accurateQueueSize)

Constructor to use a provided executor implementation for running tasks.

This constructor allows you to specify if you want accurate queue sizes to be tracked for given thread keys. There is a performance hit associated with this, so this should only be enabled if KeyDistributedExecutor.getTaskQueueSize(Object) calls will be used.

This constructs with a default expected level of concurrency of 16.

Parameters:

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

accurateQueueSize - true to make KeyDistributedExecutor.getTaskQueueSize(Object) more accurate

KeyDistributedScheduler

public KeyDistributedScheduler(SubmitterScheduler scheduler,
                               int maxTasksPerCycle)

Constructor to use a provided executor implementation for running tasks.

This constructor allows you to provide a maximum number of tasks for a key before it yields to another key. This can make it more fair, and make it so no single key can starve other keys from running. The lower this is set however, the less efficient it becomes in part because it has to give up the thread and get it again, but also because it must copy the subset of the task queue which it can run.

This constructs with a default expected level of concurrency of 16. This also does not attempt to have an accurate queue size for the KeyDistributedExecutor.getTaskQueueSize(Object) call (thus preferring high performance).

Parameters:

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

maxTasksPerCycle - maximum tasks run per key before yielding for other keys

KeyDistributedScheduler

public KeyDistributedScheduler(SubmitterScheduler scheduler,
                               int maxTasksPerCycle,
                               boolean accurateQueueSize)

Constructor to use a provided executor implementation for running tasks.

This constructor allows you to provide a maximum number of tasks for a key before it yields to another key. This can make it more fair, and make it so no single key can starve other keys from running. The lower this is set however, the less efficient it becomes in part because it has to give up the thread and get it again, but also because it must copy the subset of the task queue which it can run.

This also allows you to specify if you want accurate queue sizes to be tracked for given thread keys. There is a performance hit associated with this, so this should only be enabled if KeyDistributedExecutor.getTaskQueueSize(Object) calls will be used.

This constructs with a default expected level of concurrency of 16.

Parameters:

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

maxTasksPerCycle - maximum tasks run per key before yielding for other keys

accurateQueueSize - true to make KeyDistributedExecutor.getTaskQueueSize(Object) more accurate

KeyDistributedScheduler

public KeyDistributedScheduler(int expectedParallism,
                               SubmitterScheduler scheduler)

Constructor to use a provided scheduler implementation for running tasks.

This constructor does not attempt to have an accurate queue size for the KeyDistributedExecutor.getTaskQueueSize(Object) call (thus preferring high performance).

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:

expectedParallism - level of expected quantity of threads adding tasks in parallel

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

KeyDistributedScheduler

public KeyDistributedScheduler(int expectedParallism,
                               SubmitterScheduler scheduler,
                               boolean accurateQueueSize)

Constructor to use a provided scheduler implementation for running tasks.

This constructor allows you to specify if you want accurate queue sizes to be tracked for given thread keys. There is a performance hit associated with this, so this should only be enabled if KeyDistributedExecutor.getTaskQueueSize(Object) calls will be used.

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:

expectedParallism - level of expected quantity of threads adding tasks in parallel

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

accurateQueueSize - true to make KeyDistributedExecutor.getTaskQueueSize(Object) more accurate

KeyDistributedScheduler

public KeyDistributedScheduler(int expectedParallism,
                               SubmitterScheduler scheduler,
                               int maxTasksPerCycle)

Constructor to use a provided scheduler implementation for running tasks.

This constructor allows you to provide a maximum number of tasks for a key before it yields to another key. This can make it more fair, and make it so no single key can starve other keys from running. The lower this is set however, the less efficient it becomes in part because it has to give up the thread and get it again, but also because it must copy the subset of the task queue which it can run.

This constructor does not attempt to have an accurate queue size for the KeyDistributedExecutor.getTaskQueueSize(Object) call (thus preferring high performance).

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:

expectedParallism - level of expected quantity of threads adding tasks in parallel

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

maxTasksPerCycle - maximum tasks run per key before yielding for other keys

KeyDistributedScheduler

public KeyDistributedScheduler(int expectedParallism,
                               SubmitterScheduler scheduler,
                               int maxTasksPerCycle,
                               boolean accurateQueueSize)

Constructor to use a provided scheduler implementation for running tasks.

This constructor allows you to provide a maximum number of tasks for a key before it yields to another key. This can make it more fair, and make it so no single key can starve other keys from running. The lower this is set however, the less efficient it becomes in part because it has to give up the thread and get it again, but also because it must copy the subset of the task queue which it can run.

This also allows you to specify if you want accurate queue sizes to be tracked for given thread keys. There is a performance hit associated with this, so this should only be enabled if KeyDistributedExecutor.getTaskQueueSize(Object) calls will be used.

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:

expectedParallism - level of expected quantity of threads adding tasks in parallel

scheduler - A multi-threaded scheduler to distribute tasks to. Ideally has as many possible threads as keys that will be used in parallel.

maxTasksPerCycle - maximum tasks run per key before yielding for other keys

accurateQueueSize - true to make KeyDistributedExecutor.getTaskQueueSize(Object) more accurate

Method Detail

getSchedulerForKey

public SubmitterScheduler getSchedulerForKey(java.lang.Object threadKey)

Returns a scheduler implementation where all tasks submitted on this scheduler will run on the provided key.

Parameters:

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

Returns:

scheduler which will only execute based on the provided key

schedule

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

Schedule a one time task with a given delay that will not run concurrently based off the thread key.

Parameters:

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

task - Task to execute

delayInMs - Time to wait to execute task

submitScheduled

public ListenableFuture<?> submitScheduled(java.lang.Object threadKey,
                                           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.

Parameters:

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

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 <T> ListenableFuture<T> submitScheduled(java.lang.Object threadKey,
                                               java.lang.Runnable task,
                                               T result,
                                               long delayInMs)

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

Type Parameters:

T - type of result returned from the future

Parameters:

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

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 <T> ListenableFuture<T> submitScheduled(java.lang.Object threadKey,
                                               java.util.concurrent.Callable<T> task,
                                               long delayInMs)

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

Type Parameters:

T - type of result returned from the future

Parameters:

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

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

scheduleTaskWithFixedDelay

public void scheduleTaskWithFixedDelay(java.lang.Object threadKey,
                                       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.

Parameters:

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

task - Task to be executed.

initialDelay - Delay in milliseconds until first run.

recurringDelay - Delay in milliseconds for running task after last finish.

scheduleTaskAtFixedRate

public void scheduleTaskAtFixedRate(java.lang.Object threadKey,
                                    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).

Parameters:

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

task - runnable to be executed

initialDelay - delay in milliseconds until first run

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