PeriodicTask (LSST CCS - Utilities 2.1.18 API)

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)` Creates a periodic task.

Method Summary

All Methods Instance Methods Concrete Methods
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.
`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
`boolean`	`isCancelled()` Returns `true` if this task has been canceled.
`boolean`	`isDone()` Returns `true` if this task has completed.
`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,
                    Level logLevel,
                    long period,
                    TimeUnit unit)
```
    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
    
    logLevel - level at which exceptions thrown by this task should be logged; if null, the default level for the specified Scheduler will be used
    
    period - the period between successive executions, or the delay between executions, depending on the value of isFixedRate argument
    
    unit - the time unit of the period parameter
    
    Throws:
    
    NullPointerException - if scheduler or runnable arguments are null
- 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.
  - 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.
  - 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

Class PeriodicTask

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PeriodicTask

Method Detail

run

getFailures

getMaxFailures

getDelay

compareTo

cancel

isCancelled

isDone

get

get

setMaxFailures

setPeriod

getPeriod

stop

stop

start

start

getTaskName