org.lsst.ccs.utilities.scheduler

Class Scheduler

java.lang.Object

org.lsst.ccs.utilities.scheduler.Scheduler

All Implemented Interfaces:

Executor

public final class Scheduler
extends Object
implements Executor

Customized scheduling executor for running periodic and delayed tasks.

Methods that schedule periodic actions return instances of PeriodicTask that provide control over the task execution: cancellation, change of period, suspension and resumption. It is also possible to provide a logger for reporting uncaught exceptions thrown by periodic tasks.

The name of any idle thread of this scheduler is the name of the scheduler. The name of any active thread is [scheduler name]:[task name].

Sample Usage. The following code sketch creates a periodic task that beeps for 10 seconds, changing period after 3 seconds, then pausing for 2 seconds.

 
 Scheduler scheduler = new Scheduler("tester", 1);
 ...
 Runnable run = () -> java.awt.Toolkit.getDefaultToolkit().beep();
 PeriodicTask task = scheduler.scheduleAtFixedRate(run, 0, 1, TimeUnit.SECONDS, "bipper", Level.SEVERE);
 scheduler.schedule(() -> task.setPeriod(500, TimeUnit.MILLISECONDS), 3, TimeUnit.SECONDS);
 scheduler.schedule(() -> task.stop(), 6, TimeUnit.SECONDS);
 scheduler.schedule(() -> task.start(), 8, TimeUnit.SECONDS);
 scheduler.schedule(() -> task.cancel(false), 10, TimeUnit.SECONDS);
 ...
 scheduler.shutdown();
 

Author:

onoprien

Constructor Summary

Constructors

Constructor and Description
Scheduler(String name, int nThreads) Constructs a scheduler with a fixed number of executor threads.
Scheduler(String name, int nThreads, ThreadGroup threadGroup) Constructs a scheduler with a fixed number of executor threads.

Method Summary

Modifier and Type	Method and Description
boolean	awaitTermination(long timeout, TimeUnit unit) Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
void	execute(Runnable command) Executes a one-shot action.
int	getActiveCount() Get the (approximate) number of active threads for this scheduler.
Level	getDefaultLogLevel() Returns the default level at which uncaught exceptions thrown by scheduled tasks are logged if no level is specified at task submission.
String	getName() Returns the name of this scheduler.
int	getPoolSize() Get the size of the pool, i.e the number of threads in the pool.
int	getQueueSize() Get the queue size.
boolean	isShutdown() Returns true if this scheduler has been shut down.
boolean	isTerminated() Returns true if all tasks have completed following shut down.
<V> ScheduledFuture<V>	schedule(Callable<V> callable, Date date) Creates and executes a one-shot action that becomes enabled at the given time in the future.
<V> ScheduledFuture<V>	schedule(Callable<V> callable, long delay, TimeUnit unit) Creates and executes a one-shot action that becomes enabled after the given delay.
ScheduledFuture<?>	schedule(Runnable command, Date date) Creates and executes a one-shot action that becomes enabled at the given time in the future.
ScheduledFuture<?>	schedule(Runnable command, long delay, TimeUnit unit) Creates and executes a one-shot action that becomes enabled after the given delay.
PeriodicTask	scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit) Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period.
PeriodicTask	scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit, String taskName, Level logLevel) Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period.
PeriodicTask	scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit, String taskName, PeriodicTaskExceptionHandler exceptionHandler) Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period.
PeriodicTask	scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit) Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next.
PeriodicTask	scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit, String taskName, Level logLevel) Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next.
void	setDefaultLogLevel(Level defaultLogLevel) Modifies default level at which uncaught exceptions thrown by scheduled tasks are logged if no level is specified at task submission.
void	setLogger(Logger logger) Sets logger to be used for reporting exceptions thrown by scheduled tasks.
void	setMaxFailures(int maxFailures) Sets the default maximum number of consecutive failures (uncaught exceptions) fixedRate tasks can encounter before being suppressed.
void	shutdown() Initiates orderly shutdown of this scheduler.
void	shutdownNow() Initiates forced shutdown of this scheduler.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scheduler

public Scheduler(String name,
                 int nThreads)

Constructs a scheduler with a fixed number of executor threads.

Parameters:

name - name for threads created by this scheduler.

nThreads - number of threads.

Scheduler

public Scheduler(String name,
                 int nThreads,
                 ThreadGroup threadGroup)

Constructs a scheduler with a fixed number of executor threads.

Parameters:

name - name for threads created by this scheduler.

nThreads - number of threads.

threadGroup - Group the threads used by this scheduler should belong to.

Method Detail

shutdown

public void shutdown()

Initiates orderly shutdown of this scheduler.

shutdownNow

public void shutdownNow()

Initiates forced shutdown of this scheduler.

setLogger

public void setLogger(Logger logger)

Sets logger to be used for reporting exceptions thrown by scheduled tasks.

Parameters:

logger - Logger.

setDefaultLogLevel

public void setDefaultLogLevel(Level defaultLogLevel)

Modifies default level at which uncaught exceptions thrown by scheduled tasks are logged if no level is specified at task submission. By default, this level is WARNING.

Parameters:

defaultLogLevel - New default logging level.

setMaxFailures

public void setMaxFailures(int maxFailures)

Sets the default maximum number of consecutive failures (uncaught exceptions) fixedRate tasks can encounter before being suppressed. The default is 10. The limit associated with the scheduler can be overridden on a task-by-task basis.

Parameters:

maxFailures - Maximum number of consecutive failures; if negative, the tasks are never suppressed.

getName

public String getName()

Returns the name of this scheduler.

Returns:

Scheduler name.

getDefaultLogLevel

public Level getDefaultLogLevel()

Returns the default level at which uncaught exceptions thrown by scheduled tasks are logged if no level is specified at task submission.

Returns:

The Default log level for this scheduler.

isShutdown

public boolean isShutdown()

Returns true if this scheduler has been shut down.

Returns:

true if the scheduler has been shut down

isTerminated

public boolean isTerminated()

Returns true if all tasks have completed following shut down.

Returns:

true if all tasks have terminated.

execute

public void execute(Runnable command)

Executes a one-shot action.

Specified by:

execute in interface Executor

Parameters:

command - Task to execute.

schedule

public ScheduledFuture<?> schedule(Runnable command,
                                   long delay,
                                   TimeUnit unit)

Creates and executes a one-shot action that becomes enabled after the given delay.

Parameters:

command - the task to execute

delay - the time from now to delay execution

unit - the time unit of the delay parameter

Returns:

a PeriodicTask representing pending completion of the task, whose get() method will return null upon completion

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

schedule

public ScheduledFuture<?> schedule(Runnable command,
                                   Date date)

Creates and executes a one-shot action that becomes enabled at the given time in the future. If the specified moment in time has already passed, the execution is started immediately.

Parameters:

command - the task to execute.

date - the time when the execution should start

Returns:

a PeriodicTask representing pending completion of the task, whose get() method will return null upon completion

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

schedule

public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                       long delay,
                                       TimeUnit unit)

Creates and executes a one-shot action that becomes enabled after the given delay.

Type Parameters:

V - the type of the result

Parameters:

callable - the function to execute

delay - the time from now to delay execution

unit - the time unit of the delay parameter

Returns:

a PeriodicTask that can be used to extract result or cancel

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if callable is null

schedule

public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                       Date date)

Creates and executes a one-shot action that becomes enabled at the given time in the future. If the specified moment in time has already passed, the execution is started immediately.

Type Parameters:

V - the type of the result

Parameters:

callable - the function to execute

date - the time when the execution should start

Returns:

a PeriodicTask that can be used to extract result or cancel

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if callable is null

scheduleAtFixedRate

public PeriodicTask scheduleAtFixedRate(Runnable command,
                                        long initialDelay,
                                        long period,
                                        TimeUnit unit,
                                        String taskName,
                                        PeriodicTaskExceptionHandler exceptionHandler)

Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor. If any execution of this task takes longer than its period, then subsequent executions may start late, but will not concurrently execute.

Parameters:

command - the task to execute

initialDelay - the time to delay first execution

period - the period between successive executions

unit - the time unit of the initialDelay and period parameters

taskName - task name, used to identify failed tasks in the log

exceptionHandler - Handler that defines response to any abnormal circumstances; if null, the default handler will be used.

Returns:

a PeriodicTask representing pending completion of the task, and whose get() method will throw an exception upon cancellation

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

IllegalArgumentException - if period less than or equal to zero

scheduleAtFixedRate

public PeriodicTask scheduleAtFixedRate(Runnable command,
                                        long initialDelay,
                                        long period,
                                        TimeUnit unit,
                                        String taskName,
                                        Level logLevel)

Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor. If any execution of this task takes longer than its period, then subsequent executions may start late, but will not concurrently execute.

Parameters:

command - the task to execute

initialDelay - the time to delay first execution

period - the period between successive executions

unit - the time unit of the initialDelay and period parameters

taskName - task name, used to identify failed tasks in the log

logLevel - level at which exceptions thrown by scheduled tasks should be logged

Returns:

a PeriodicTask representing pending completion of the task, and whose get() method will throw an exception upon cancellation

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

IllegalArgumentException - if period less than or equal to zero

scheduleAtFixedRate

public PeriodicTask scheduleAtFixedRate(Runnable command,
                                        long initialDelay,
                                        long period,
                                        TimeUnit unit)

Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given period. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor. If any execution of this task takes longer than its period, then subsequent executions may start late, but will not concurrently execute.

Parameters:

command - the task to execute

initialDelay - the time to delay first execution

period - the period between successive executions

unit - the time unit of the initialDelay and period parameters

Returns:

a PeriodicTask representing pending completion of the task, and whose get() method will throw an exception upon cancellation

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

IllegalArgumentException - if period less than or equal to zero

scheduleWithFixedDelay

public PeriodicTask scheduleWithFixedDelay(Runnable command,
                                           long initialDelay,
                                           long delay,
                                           TimeUnit unit,
                                           String taskName,
                                           Level logLevel)

Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next.

Parameters:

command - the task to execute

initialDelay - the time to delay first execution

delay - the delay between the termination of one execution and the commencement of the next

unit - the time unit of the initialDelay and delay parameters

taskName - task name, used to identify failed tasks in the log

logLevel - level at which exceptions thrown by scheduled tasks should be logged

Returns:

a PeriodicTask representing pending completion of the task, and whose get() method will throw an exception upon cancellation

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

IllegalArgumentException - if delay less than or equal to zero

scheduleWithFixedDelay

public PeriodicTask scheduleWithFixedDelay(Runnable command,
                                           long initialDelay,
                                           long delay,
                                           TimeUnit unit)

Creates and executes a fixedRate action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next.

Parameters:

command - the task to execute

initialDelay - the time to delay first execution

delay - the delay between the termination of one execution and the commencement of the next

unit - the time unit of the initialDelay and delay parameters

Returns:

a PeriodicTask representing pending completion of the task, and whose get() method will throw an exception upon cancellation

Throws:

RejectedExecutionException - if the task cannot be scheduled for execution

NullPointerException - if command is null

IllegalArgumentException - if delay less than or equal to zero

awaitTermination

public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException

Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Parameters:

timeout - the maximum time to wait.

unit - the time unit of the timeout argument.

Returns:

true if this executor terminated and false if the timeout elapsed before termination.

Throws:

InterruptedException - if interrupted while waiting

getActiveCount

public int getActiveCount()

Get the (approximate) number of active threads for this scheduler.

Returns:

the number of active threads.

getQueueSize

public int getQueueSize()

Get the queue size.

Returns:

get the size of the queue

getPoolSize

public int getPoolSize()

Get the size of the pool, i.e the number of threads in the pool.

Returns:

the number of threads in the pool