Package org.threadly.concurrent.wrapper

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

    • 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