org.threadly.test.concurrent

Class TestableScheduler

java.lang.Object

org.threadly.test.concurrent.TestableScheduler

All Implemented Interfaces:

java.util.concurrent.Executor, org.threadly.concurrent.PrioritySchedulerService, org.threadly.concurrent.SchedulerService, org.threadly.concurrent.SubmitterExecutor, org.threadly.concurrent.SubmitterScheduler

public class TestableScheduler
extends java.lang.Object
implements org.threadly.concurrent.PrioritySchedulerService

This differs from NoThreadScheduler in that time is ONLY advanced via the tick calls. That means that if you schedule a task, it will be scheduled off of either the creation time, or the last tick time, what ever the most recent point is. This allows you to progress time forward faster than it could in real time, having tasks execute faster, etc, etc.

The tasks in this scheduler are only progressed forward with calls to tick(). Since it is running on the calling thread, calls to Object.wait() and Thread.sleep() from sub tasks will block (possibly forever). The call to tick() will not unblock till there is no more work for the scheduler to currently handle.

Since:

1.0 (since 2.0.0 in threadly artifact)

Constructor Summary

Constructors

Constructor and Description
TestableScheduler() Constructs a new TestableScheduler scheduler.
TestableScheduler(org.threadly.concurrent.TaskPriority defaultPriority, long maxWaitForLowPriorityInMs) Constructs a new TestableScheduler scheduler.

Method Summary

Modifier and Type	Method and Description
int	advance(long timeInMillis) This is to provide a convince when advancing the scheduler forward an explicit amount of time.
int	advance(long timeInMillis, org.threadly.util.ExceptionHandler exceptionHandler) This is to provide a convince when advancing the scheduler forward an explicit amount of time.
java.util.List<java.lang.Runnable>	clearTasks() Removes any tasks waiting to be run.
void	execute(java.lang.Runnable task)
void	execute(java.lang.Runnable task, org.threadly.concurrent.TaskPriority priority)
int	getActiveTaskCount()
org.threadly.concurrent.TaskPriority	getDefaultPriority()
long	getDelayTillNextTask() Checks how long till the next task will be ready to execute.
long	getLastTickTime() Returns the last provided time to the tick call.
long	getMaxWaitForLowPriority()
int	getQueuedTaskCount()
int	getQueuedTaskCount(org.threadly.concurrent.TaskPriority priority)
int	getWaitingForExecutionTaskCount()
int	getWaitingForExecutionTaskCount(org.threadly.concurrent.TaskPriority priority)
boolean	hasTaskReadyToRun() Checks if there are tasks ready to be run on the scheduler.
boolean	isShutdown()
boolean	remove(java.util.concurrent.Callable<?> task)
boolean	remove(java.lang.Runnable task)
void	schedule(java.lang.Runnable task, long delayInMs)
void	schedule(java.lang.Runnable task, long delayInMs, org.threadly.concurrent.TaskPriority priority)
void	scheduleAtFixedRate(java.lang.Runnable task, long initialDelay, long period)
void	scheduleAtFixedRate(java.lang.Runnable task, long initialDelay, long period, org.threadly.concurrent.TaskPriority priority)
void	scheduleWithFixedDelay(java.lang.Runnable task, long initialDelay, long recurringDelay)
void	scheduleWithFixedDelay(java.lang.Runnable task, long initialDelay, long recurringDelay, org.threadly.concurrent.TaskPriority priority)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submit(java.util.concurrent.Callable<T> task)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submit(java.util.concurrent.Callable<T> task, org.threadly.concurrent.TaskPriority priority)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submit(java.lang.Runnable task, T result)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submit(java.lang.Runnable task, T result, org.threadly.concurrent.TaskPriority priority)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submitScheduled(java.util.concurrent.Callable<T> task, long delayInMs)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submitScheduled(java.util.concurrent.Callable<T> task, long delayInMs, org.threadly.concurrent.TaskPriority priority)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submitScheduled(java.lang.Runnable task, T result, long delayInMs)
<T> org.threadly.concurrent.future.ListenableFuture<T>	submitScheduled(java.lang.Runnable task, T result, long delayInMs, org.threadly.concurrent.TaskPriority priority)
int	tick() Progresses tasks for the current time.
int	tick(org.threadly.util.ExceptionHandler exceptionHandler) Progresses tasks for the current time.
int	tick(long currentTime) This progresses tasks based off the time provided.
int	tick(long currentTime, org.threadly.util.ExceptionHandler exceptionHandler) This progresses tasks based off the time provided.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.threadly.concurrent.PrioritySchedulerService

submit, submitScheduled

Methods inherited from interface org.threadly.concurrent.SubmitterScheduler

submitScheduled

Methods inherited from interface org.threadly.concurrent.SubmitterExecutor

submit

Constructor Detail

TestableScheduler

public TestableScheduler()

Constructs a new TestableScheduler scheduler.

TestableScheduler

public TestableScheduler(org.threadly.concurrent.TaskPriority defaultPriority,
                         long maxWaitForLowPriorityInMs)

Constructs a new TestableScheduler scheduler.

Parameters:

defaultPriority - Default priority for tasks which are submitted without any specified priority

maxWaitForLowPriorityInMs - time low priority tasks to wait if there are high priority tasks ready to run

Method Detail

isShutdown

public boolean isShutdown()

Specified by:

isShutdown in interface org.threadly.concurrent.SchedulerService

getActiveTaskCount

public int getActiveTaskCount()

Specified by:

getActiveTaskCount in interface org.threadly.concurrent.SchedulerService

getQueuedTaskCount

public int getQueuedTaskCount()

Specified by:

getQueuedTaskCount in interface org.threadly.concurrent.SchedulerService

getWaitingForExecutionTaskCount

public int getWaitingForExecutionTaskCount()

Specified by:

getWaitingForExecutionTaskCount in interface org.threadly.concurrent.SchedulerService

getDefaultPriority

public org.threadly.concurrent.TaskPriority getDefaultPriority()

Specified by:

getDefaultPriority in interface org.threadly.concurrent.PrioritySchedulerService

getMaxWaitForLowPriority

public long getMaxWaitForLowPriority()

Specified by:

getMaxWaitForLowPriority in interface org.threadly.concurrent.PrioritySchedulerService

getQueuedTaskCount

public int getQueuedTaskCount(org.threadly.concurrent.TaskPriority priority)

Specified by:

getQueuedTaskCount in interface org.threadly.concurrent.PrioritySchedulerService

getWaitingForExecutionTaskCount

public int getWaitingForExecutionTaskCount(org.threadly.concurrent.TaskPriority priority)

Specified by:

getWaitingForExecutionTaskCount in interface org.threadly.concurrent.PrioritySchedulerService

remove

public boolean remove(java.lang.Runnable task)

Specified by:

remove in interface org.threadly.concurrent.SchedulerService

remove

public boolean remove(java.util.concurrent.Callable<?> task)

Specified by:

remove in interface org.threadly.concurrent.SchedulerService

execute

public void execute(java.lang.Runnable task)

Specified by:

execute in interface java.util.concurrent.Executor

submit

public <T> org.threadly.concurrent.future.ListenableFuture<T> submit(java.util.concurrent.Callable<T> task)

Specified by:

submit in interface org.threadly.concurrent.SubmitterExecutor

submit

public <T> org.threadly.concurrent.future.ListenableFuture<T> submit(java.lang.Runnable task,
                                                                     T result)

Specified by:

submit in interface org.threadly.concurrent.SubmitterExecutor

schedule

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

Specified by:

schedule in interface org.threadly.concurrent.SubmitterScheduler

submitScheduled

public <T> org.threadly.concurrent.future.ListenableFuture<T> submitScheduled(java.util.concurrent.Callable<T> task,
                                                                              long delayInMs)

Specified by:

submitScheduled in interface org.threadly.concurrent.SubmitterScheduler

submitScheduled

public <T> org.threadly.concurrent.future.ListenableFuture<T> submitScheduled(java.lang.Runnable task,
                                                                              T result,
                                                                              long delayInMs)

Specified by:

submitScheduled in interface org.threadly.concurrent.SubmitterScheduler

execute

public void execute(java.lang.Runnable task,
                    org.threadly.concurrent.TaskPriority priority)

Specified by:

execute in interface org.threadly.concurrent.PrioritySchedulerService

submit

public <T> org.threadly.concurrent.future.ListenableFuture<T> submit(java.util.concurrent.Callable<T> task,
                                                                     org.threadly.concurrent.TaskPriority priority)

Specified by:

submit in interface org.threadly.concurrent.PrioritySchedulerService

submit

public <T> org.threadly.concurrent.future.ListenableFuture<T> submit(java.lang.Runnable task,
                                                                     T result,
                                                                     org.threadly.concurrent.TaskPriority priority)

Specified by:

submit in interface org.threadly.concurrent.PrioritySchedulerService

schedule

public void schedule(java.lang.Runnable task,
                     long delayInMs,
                     org.threadly.concurrent.TaskPriority priority)

Specified by:

schedule in interface org.threadly.concurrent.PrioritySchedulerService

submitScheduled

public <T> org.threadly.concurrent.future.ListenableFuture<T> submitScheduled(java.util.concurrent.Callable<T> task,
                                                                              long delayInMs,
                                                                              org.threadly.concurrent.TaskPriority priority)

Specified by:

submitScheduled in interface org.threadly.concurrent.PrioritySchedulerService

submitScheduled

public <T> org.threadly.concurrent.future.ListenableFuture<T> submitScheduled(java.lang.Runnable task,
                                                                              T result,
                                                                              long delayInMs,
                                                                              org.threadly.concurrent.TaskPriority priority)

Specified by:

submitScheduled in interface org.threadly.concurrent.PrioritySchedulerService

scheduleWithFixedDelay

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

Specified by:

scheduleWithFixedDelay in interface org.threadly.concurrent.SubmitterScheduler

scheduleAtFixedRate

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

Specified by:

scheduleAtFixedRate in interface org.threadly.concurrent.SubmitterScheduler

scheduleWithFixedDelay

public void scheduleWithFixedDelay(java.lang.Runnable task,
                                   long initialDelay,
                                   long recurringDelay,
                                   org.threadly.concurrent.TaskPriority priority)

Specified by:

scheduleWithFixedDelay in interface org.threadly.concurrent.PrioritySchedulerService

scheduleAtFixedRate

public void scheduleAtFixedRate(java.lang.Runnable task,
                                long initialDelay,
                                long period,
                                org.threadly.concurrent.TaskPriority priority)

Specified by:

scheduleAtFixedRate in interface org.threadly.concurrent.PrioritySchedulerService

getLastTickTime

public long getLastTickTime()

Returns the last provided time to the tick call. If tick has not been called yet, then this will represent the time at construction.

Returns:

last time the scheduler used for reference on execution

advance

public int advance(long timeInMillis)

This is to provide a convince when advancing the scheduler forward an explicit amount of time. Where tick accepts an absolute time, this accepts an amount of time to advance forward. That way the user does not have to track the current time.

Parameters:

timeInMillis - amount in milliseconds to advance the scheduler forward

Returns:

quantity of tasks run during this tick call

advance

public int advance(long timeInMillis,
                   org.threadly.util.ExceptionHandler exceptionHandler)

This is to provide a convince when advancing the scheduler forward an explicit amount of time. Where tick accepts an absolute time, this accepts an amount of time to advance forward. That way the user does not have to track the current time.

This call allows you to specify an ExceptionHandler. If provided, if any tasks throw an exception, this will be called to inform them of the exception. This allows you to ensure that you get a returned task count (meaning if provided, no exceptions except a possible InterruptedException can be thrown). If null is provided for the exception handler, than any tasks which throw a RuntimeException, will throw out of this invocation.

Parameters:

timeInMillis - amount in milliseconds to advance the scheduler forward

exceptionHandler - Exception handler implementation to call if any tasks throw an exception, or null to have exceptions thrown out of this call

Returns:

quantity of tasks run during this tick call

tick

public int tick()

Progresses tasks for the current time. This will block as it runs as many scheduled or waiting tasks as possible. This call will NOT block if no task are currently ready to run.

If any tasks throw a RuntimeException, they will be bubbled up to this tick call. Any tasks past that task will not run till the next call to tick. So it is important that the implementor handle those exceptions.

Returns:

quantity of tasks run during this tick call

tick

public int tick(org.threadly.util.ExceptionHandler exceptionHandler)

Progresses tasks for the current time. This will block as it runs as many scheduled or waiting tasks as possible. This call will NOT block if no task are currently ready to run.

This call allows you to specify an ExceptionHandler. If provided, if any tasks throw an exception, this will be called to inform them of the exception. This allows you to ensure that you get a returned task count (meaning if provided, no exceptions except a possible InterruptedException can be thrown). If null is provided for the exception handler, than any tasks which throw a RuntimeException, will throw out of this invocation.

Parameters:

exceptionHandler - Exception handler implementation to call if any tasks throw an exception, or null to have exceptions thrown out of this call

Returns:

quantity of tasks run during this tick call

tick

public int tick(long currentTime)

This progresses tasks based off the time provided. This is primarily used in testing by providing a possible time in the future (to execute future tasks). This call will NOT block if no task are currently ready to run.

If any tasks throw a RuntimeException, they will be bubbled up to this tick call. Any tasks past that task will not run till the next call to tick. So it is important that the implementor handle those exceptions.

This call accepts the absolute time in milliseconds. If you want to advance the scheduler a specific amount of time forward, look at the "advance" call.

Parameters:

currentTime - Absolute time to provide for looking at task run time

Returns:

quantity of tasks run in this tick call

tick

public int tick(long currentTime,
                org.threadly.util.ExceptionHandler exceptionHandler)

This progresses tasks based off the time provided. This is primarily used in testing by providing a possible time in the future (to execute future tasks). This call will NOT block if no task are currently ready to run.

This call allows you to specify an ExceptionHandler. If provided, if any tasks throw an exception, this will be called to inform them of the exception. This allows you to ensure that you get a returned task count (meaning if provided, no exceptions except a possible InterruptedException can be thrown). If null is provided for the exception handler, than any tasks which throw a RuntimeException, will throw out of this invocation.

This call accepts the absolute time in milliseconds. If you want to advance the scheduler a specific amount of time forward, look at the "advance" call.

Parameters:

currentTime - Absolute time to provide for looking at task run time

exceptionHandler - Exception handler implementation to call if any tasks throw an exception, or null to have exceptions thrown out of this call

Returns:

quantity of tasks run in this tick call

hasTaskReadyToRun

public boolean hasTaskReadyToRun()

Checks if there are tasks ready to be run on the scheduler. If tick(ExceptionHandler) is not currently being called, this call indicates if the next tick(ExceptionHandler) will have at least one task to run. If tick(ExceptionHandler) is currently being invoked, this call will do a best attempt to indicate if there is at least one more task to run (not including the task which may currently be running). It's a best attempt as it will try not to block the thread invoking tick(ExceptionHandler) to prevent it from accepting additional work.

Returns:

true if there are task waiting to run

getDelayTillNextTask

public long getDelayTillNextTask()

Checks how long till the next task will be ready to execute. If there are no tasks in this scheduler currently then Long.MAX_VALUE will be returned. If there is a task ready to execute this will return a value less than or equal to zero. If the task is past its desired point of execution the result will be a negative amount of milliseconds past that point in time.

Generally this is called from the same thread that would invoke tick(ExceptionHandler) (but does not have to be). Since this does not block or lock if being invoked in parallel with tick(ExceptionHandler), the results may be no longer accurate by the time this invocation has returned.

This can be useful if you want to know how long you can block on something, ASSUMING you can detect that something has been added to the scheduler, and interrupt that blocking in order to handle tasks.

Returns:

Milliseconds till the next task is ready to run

clearTasks

public java.util.List<java.lang.Runnable> clearTasks()

Removes any tasks waiting to be run. Will not interrupt any tasks currently running if tick(ExceptionHandler) is being called. But will avoid additional tasks from being run on the current tick(ExceptionHandler) call.

If tasks are added concurrently during this invocation they may or may not be removed.

Returns:

List of runnables which were waiting in the task queue to be executed (and were now removed)