org.lsst.ccs.utilities.scheduler

Class PeriodicTaskExceptionHandler

java.lang.Object

org.lsst.ccs.utilities.scheduler.PeriodicTaskExceptionHandler

public class PeriodicTaskExceptionHandler
extends Object

Defines behavior of PeriodicTask under abnormal circumstances. Setters provided by this class can be used to establish policies the periodic task should follow when it throws an exception or runs for an unusually long time. Callback methods onXXX(PeriodicTask task, ... can be overridden to execute client code under these circumstances. They should be implemented to finish quickly, any time consuming or potentially blocking operations should be offloaded to other threads. Default implementations provided by this class log messages at the level set through a call to setLevel(...) or inherited from the Scheduler where the task runs.

Sample Usage. The following code sketch creates a fixed rate task that will skip execution if the previous one has not finished, log a message if an execution is taking longer than the task period, and quit after 2 failures.

 
 Scheduler scheduler = new Scheduler("tester", 1);
 ...
 PeriodicTaskExceptionHandler exceptionHandler = new PeriodicTaskExceptionHandler() {
     public void onLongExecution(PeriodicTask task) {
         Logger logger = task.getLogger();
         if (logger != null) {
             logger.log(getLevel(), "Task "+ task.getTaskName() +" is taking more than its period.", (Object[])null);
         }
         alertOperator();
     }
 };
 exceptionHandler.setSkipOverdueExecutions(true);
 exceptionHandler.setDetectLongExecutions(true);
 exceptionHandler.setMaxFailures(2);
 exceptionHandler.setResetFailureCountOnSuccess(false);
 scheduler.scheduleAtFixedRate(command, 0, 1, TimeUnit.SECONDS, "Task name", exceptionHandler);
 ...
 

Author:

onoprien

Constructor Summary

Constructors

Constructor and Description
PeriodicTaskExceptionHandler()

Method Summary

Modifier and Type	Method and Description
Level	getLevel()
int	getLongExecutionThreshold()
int	getMaxFailures()
boolean	isDetectLongExecutions()
boolean	isResetFailureCountOnSuccess()
boolean	isSkipOverdueExecutions()
void	onException(PeriodicTask task, Throwable exception) Called when a task throws an exception, but is not going to be terminated.
void	onFinalException(PeriodicTask task, Throwable exception) Called when a task throws an exception, and is going to be terminated.
void	onLongExecution(PeriodicTask task) Called when an execution that takes longer than the task period is detected.
void	onSkippedExecutions(PeriodicTask task, int nSkipped) Called when a fixed rate task executes after skipping one or more previous executions that could not start on time.
void	setDetectLongExecutions(boolean detectLongExecutions) Sets a policy on whether or not executions that take longer than the task period to complete should be detected and onLongExecution(...) called.
void	setLevel(Level level) Sets logging level.
void	setLongExecutionThreshold(int longExecutionThreshold, TimeUnit unit) Sets a policy on detecting long executions.
void	setMaxFailures(int maxFailures) Sets the number of times the task can throw an exception before it is terminated.
void	setResetFailureCountOnSuccess(boolean resetFailureCountOnSuccess) Sets a policy on whether or not only consecutive failures should be counted towards the allowed maximum.
void	setSkipOverdueExecutions(boolean skipOverdueExecutions) Sets a policy on skipping executions that cannot start on time.

Methods inherited from class java.lang.Object

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

Constructor Detail

PeriodicTaskExceptionHandler

public PeriodicTaskExceptionHandler()

Method Detail

setSkipOverdueExecutions

public void setSkipOverdueExecutions(boolean skipOverdueExecutions)

Sets a policy on skipping executions that cannot start on time. This flag is only relevant for fixed rate tasks, and can be set to true to prevent executions from piling up when a previous execution takes a long time, and then running in rapid succession when it finally finishes. This option is usually not suitable for task periods less than 100 milliseconds. The default is false.

Parameters:

skipOverdueExecutions - If true, executions that cannot start on time are skipped.

setDetectLongExecutions

public void setDetectLongExecutions(boolean detectLongExecutions)

Sets a policy on whether or not executions that take longer than the task period to complete should be detected and onLongExecution(...) called. Note that setting this flag to true adds significant overhead, and is usually not suitable for task periods of less than 100 milliseconds. The default is false.

Calling this method with true is equivalent to setLongExecutionThreshold(1, null); Calling this method with false is equivalent to setLongExecutionThreshold(0, null);

Parameters:

detectLongExecutions - true if long executions should be detected.

setLongExecutionThreshold

public void setLongExecutionThreshold(int longExecutionThreshold,
                                      TimeUnit unit)

Sets a policy on detecting long executions. Executions that take longer than longExecutionThreshold to complete should be detected and onLongExecution(...) called. Note that detecting long executions adds significant overhead, and is usually not suitable for task periods of less than 100 milliseconds.

If the threshold is set to zero (default), long executions are not detected. If the unit is null, the value of longExecutionThreshold is interpreted as the number of task periods.

Parameters:

longExecutionThreshold - Threshold.

unit - Init for threshold.

setMaxFailures

public void setMaxFailures(int maxFailures)

Sets the number of times the task can throw an exception before it is terminated.

Parameters:

maxFailures - Allowed number of failures.

setResetFailureCountOnSuccess

public void setResetFailureCountOnSuccess(boolean resetFailureCountOnSuccess)

Sets a policy on whether or not only consecutive failures should be counted towards the allowed maximum. The default is true.

Parameters:

resetFailureCountOnSuccess - If true, only consecutive failures are counted towards the allowed maximum.

setLevel

public void setLevel(Level level)

Sets logging level.

Parameters:

level - Level.

isSkipOverdueExecutions

public boolean isSkipOverdueExecutions()

isDetectLongExecutions

public boolean isDetectLongExecutions()

getLongExecutionThreshold

public int getLongExecutionThreshold()

getMaxFailures

public int getMaxFailures()

isResetFailureCountOnSuccess

public boolean isResetFailureCountOnSuccess()

getLevel

public Level getLevel()

onSkippedExecutions

public void onSkippedExecutions(PeriodicTask task,
                                int nSkipped)

Called when a fixed rate task executes after skipping one or more previous executions that could not start on time. The default implementation logs a message.

Parameters:

task - Periodic task.

nSkipped - Number of skipped executions.

onLongExecution

public void onLongExecution(PeriodicTask task)

Called when an execution that takes longer than the task period is detected. This method is only called if detectLongExecutions property has been set to true. The default implementation logs a message.

Parameters:

task - Periodic task.

onException

public void onException(PeriodicTask task,
                        Throwable exception)

Called when a task throws an exception, but is not going to be terminated. If this method throws an exception, the task will terminate. The default implementation logs a message.

Parameters:

task - Periodic task.

exception - Thrown exception.

onFinalException

public void onFinalException(PeriodicTask task,
                             Throwable exception)

Called when a task throws an exception, and is going to be terminated. The default implementation logs a message.

Parameters:

task - Periodic task.

exception - Thrown exception.