org.lsst.ccs.utilities.scheduler

Class PeriodicTask

java.lang.Object

org.lsst.ccs.utilities.scheduler.PeriodicTask

All Implemented Interfaces:

Comparable<Delayed>, Runnable, Delayed, Future<Void>, ScheduledFuture<Void>

public class PeriodicTask
extends Object
implements Runnable, ScheduledFuture<Void>

Represents a periodic task submitted to a Scheduler. Can be used to control the task execution.

Sample Usage. The following code sketch demonstrates explicit construction of a periodic task.

 
 class Agent {
 
   private Scheduler scheduler;
   private PeriodicTask heartbeat;
   ...
 
   Agent() {
     scheduler = new Scheduler("tester", 3);
     heartbeat = new PeriodicTask(scheduler, this::broadcast, true, "heartbeat", Level.SEVERE, 5, TimeUnit.SECONDS);
     ...
   }
 
   public void start() {
     ...
     heartbeat.start();
   }
 
   ... 
 }

See Scheduler documentation for an example of creating an instance of PeriodicTask by submitting a Runnuble to a Scheduler.

Author:

onoprien

Constructor Summary

Constructors

Constructor and Description
PeriodicTask(Scheduler scheduler, Runnable runnable, boolean isFixedRate, String taskName, Level logLevel, long period, TimeUnit unit)
PeriodicTask(Scheduler scheduler, Runnable runnable, boolean isFixedRate, String taskName, long period, TimeUnit unit, PeriodicTaskExceptionHandler exceptionHandler) Creates a periodic task.

Method Summary

Modifier and Type	Method and Description
boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this task.
int	compareTo(Delayed o)
Void	get() Blocks until the task is canceled.
Void	get(long timeout, TimeUnit unit) Blocks until the task is canceled or the timeout expires.
long	getDelay(TimeUnit unit) Returns the remaining delay associated with this task, in the given time unit.
int	getFailures() Get the number of failures that occurred in this Periodic task.
Logger	getLog() Returns the logger used by this task.
Logger	getLogger() Deprecated. Use getLog() instead.
Level	getLogLevel() Returns the log level set for reporting abnormal circumstances related to this task.
int	getMaxFailures() Get the maximum number of consecutive failures for this task.
long	getPeriod(TimeUnit unit) Returns execution period of this task.
String	getTaskName() Get the name of this PeriodicTask
Thread	getThread() Returns the thread currently executing this task.
boolean	isCancelled() Returns true if this task has been canceled.
boolean	isDone() Returns true if this task has completed.
static void	main(String... args)
void	resetFailureCount() Resets failure count.
void	run()
void	setMaxFailures(int maxFailures) Sets the maximum number of consecutive failures (uncaught exceptions) this task can encounter before being suppressed.
void	setPeriod(long period, TimeUnit unit) Modifies execution period of this task.
boolean	start() Starts executing this task if it is not already being executed.
boolean	start(long initialDelay, TimeUnit unit) Starts executing this task if it is not already being executed.
void	stop() Suspends further executions of this periodic task.
void	stop(long timeout, TimeUnit unit) Suspends further executions of this periodic task.

Methods inherited from class java.lang.Object

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

Constructor Detail

PeriodicTask

public PeriodicTask(Scheduler scheduler,
                    Runnable runnable,
                    boolean isFixedRate,
                    String taskName,
                    long period,
                    TimeUnit unit,
                    PeriodicTaskExceptionHandler exceptionHandler)

Creates a periodic task. The task will not be submitted for execution until one of its start(...) methods is called.

Parameters:

scheduler - Scheduler where this task will run

runnable - Runnable to execute

isFixedRate - true if this task will be executed at fixed rate; false if this task will be run with fixed delay

taskName - Name of this task; if null, no name will be used.

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

period - Period between successive executions, or the delay between executions, depending on the value of isFixedRate argument.

unit - Time unit of the period parameter.

Throws:

NullPointerException - if scheduler or runnable arguments are null

PeriodicTask

public PeriodicTask(Scheduler scheduler,
                    Runnable runnable,
                    boolean isFixedRate,
                    String taskName,
                    Level logLevel,
                    long period,
                    TimeUnit unit)

Method Detail

run

public void run()

Specified by:

run in interface Runnable

getFailures

public int getFailures()

Get the number of failures that occurred in this Periodic task.

Returns:

the number of failures so far.

getMaxFailures

public int getMaxFailures()

Get the maximum number of consecutive failures for this task.

Returns:

the maximum number of failures for this task.

getThread

public Thread getThread()

Returns the thread currently executing this task. This method can be called on any thread, but there is no guarantee the returned thread will still be running this task by the time it returns. This method is intended for troubleshooting long-running tasks.

Returns:

Thread currently executing this task.

getDelay

public long getDelay(TimeUnit unit)

Returns the remaining delay associated with this task, in the given time unit.

Specified by:

getDelay in interface Delayed

Parameters:

unit - the time unit

Returns:

the remaining delay; zero or negative values indicate that the delay has already elapsed

compareTo

public int compareTo(Delayed o)

Specified by:

compareTo in interface Comparable<Delayed>

cancel

public boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel execution of this task. This attempt will fail if the task has already completed, has already been canceled, or could not be canceled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.

After this method returns, subsequent calls to isDone() will always return true. Subsequent calls to isCancelled() will always return true if this method returned true.

Specified by:

cancel in interface Future<Void>

Parameters:

mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete

Returns:

false if the task could not be canceled, typically because it has already completed normally; true otherwise

isCancelled

public boolean isCancelled()

Returns true if this task has been canceled.

Specified by:

isCancelled in interface Future<Void>

isDone

public boolean isDone()

Returns true if this task has completed. Completion may be due to normal termination, an exception, or cancellation - in all of these cases, this method will return true.

Specified by:

isDone in interface Future<Void>

get

public Void get()
         throws InterruptedException,
                ExecutionException

Blocks until the task is canceled.

Specified by:

get in interface Future<Void>

Returns:

null

Throws:

CancellationException - if the computation was canceled

ExecutionException - if the computation threw an exception

InterruptedException - if the current thread was interrupted while waiting

get

public Void get(long timeout,
                TimeUnit unit)
         throws InterruptedException,
                ExecutionException,
                TimeoutException

Blocks until the task is canceled or the timeout expires.

Specified by:

get in interface Future<Void>

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

null

Throws:

CancellationException - if the computation was canceled

ExecutionException - if the computation threw an exception

InterruptedException - if the current thread was interrupted while waiting

TimeoutException - if the wait timed out

setMaxFailures

public void setMaxFailures(int maxFailures)

Sets the maximum number of consecutive failures (uncaught exceptions) this task can encounter before being suppressed. By default, the tasks use the maximum number of failures associated with the scheduler they run on.

Parameters:

maxFailures - Maximum number of consecutive failures; if negative, the task is never suppressed.

resetFailureCount

public void resetFailureCount()

Resets failure count.

setPeriod

public void setPeriod(long period,
                      TimeUnit unit)

Modifies execution period of this task. Non-positive period means the task will not be executed until the period is modified. If the period is changed while a task is running, two executions can overlap in time. If this is undesirable, call stop(long, TimeUnit) before modifying the period, then call start().

Parameters:

period - the desired period.

unit - the time unit of the period argument

getPeriod

public long getPeriod(TimeUnit unit)

Returns execution period of this task.

Parameters:

unit - time unit for the returned value

Returns:

execution period of this task in specified units.

stop

public void stop()

Suspends further executions of this periodic task. Suspended tasks can be resumed with the same period by a call to start(). This method returns without waiting for the currently running execution of this task to complete. Calling this method on a task that is already suspended has no effect.

stop

public void stop(long timeout,
                 TimeUnit unit)
          throws InterruptedException,
                 TimeoutException

Suspends further executions of this periodic task. Suspended tasks can be resumed with the same period by a call to start(). This method blocks until the currently running execution of this task is complete, or the timeout has expired. Calling this method on a task that is already suspended has no effect.

Parameters:

timeout - the maximum time to wait; if 0, will wait indefinitely

unit - the time unit of the timeout argument

Throws:

InterruptedException - if the current thread was interrupted while waiting

TimeoutException - if the wait timed out

start

public boolean start()

Starts executing this task if it is not already being executed.

Returns:

false if this task was already being executed; true otherwise

start

public boolean start(long initialDelay,
                     TimeUnit unit)

Starts executing this task if it is not already being executed.

Parameters:

initialDelay - the time to delay first execution

unit - the time unit of the initialDelay parameter

Returns:

false if this task was already being executed; true otherwise

getTaskName

public String getTaskName()

Get the name of this PeriodicTask

Returns:

the PeriodicTask name

getLog

public Logger getLog()

Returns the logger used by this task.

Returns:

Logger used by this task, or null if no logger has been set on the Scheduler where this task runs.

getLogger

@Deprecated
public Logger getLogger()

Deprecated. Use getLog() instead.

Returns the logger used by this task.

Returns:

Logger used by this task, or null if no logger has been set on the Scheduler where this task runs.

getLogLevel

public Level getLogLevel()

Returns the log level set for reporting abnormal circumstances related to this task.

Returns:

Log level.

main

public static void main(String... args)