Package com.cosylab.epics.caj.util

Class Timer

java.lang.Object

java.lang.Thread

com.cosylab.epics.caj.util.Timer

All Implemented Interfaces:

Runnable

public class Timer
extends Thread

Timer. Based on EDU.oswego.cs.dl.util.concurrent (it was not appropriate for CAJ usage). Timer tasks should complete quickly. If a timer task takes excessive time to complete, it "hogs" the timer's task execution thread. This can, in turn, delay the execution of subsequent tasks, which may "bunch up" and execute in rapid succession when (and if) the offending task finally completes.

Version:

$id$

Author:

Matej Sekoranja

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected class	Timer.RunLoop	The runloop is isolated in its own Runnable class just so that the main class need not implement Runnable, which would allow others to directly invoke run, which is not supported.
static interface	Timer.TimerRunnable	Timer runnable interface.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field	Description
protected PriorityBlockingQueue<com.cosylab.epics.caj.util.Timer.TaskNode>	heap_	Tasks are maintained in a standard priority queue.
protected Timer.RunLoop	runLoop_
protected Thread	thread_	The thread used to process commands

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor	Description
Timer()	Protected constructor (singleton pattern).

Method Summary

Modifier and Type	Method	Description
static void	cancel(Object taskID)	Cancel a scheduled task that has not yet been run.
protected void	clearThread()	set thread_ to null to indicate termination
Object	executeAfterDelay(long millisecondsToDelay, Timer.TimerRunnable command)	Excecute the given command after waiting for the given delay.
Object	executePeriodically(long period, Timer.TimerRunnable command, long firstTime)	Execute the given command every period milliseconds AT FIXED RATE.
protected com.cosylab.epics.caj.util.Timer.TaskNode	nextTask()	Return the next task to execute, or null if thread is interrupted.
void	restart()	Start (or restart) a thread to process commands, or wake up an existing thread if one is already running.
void	shutDown()	Cancel all tasks and interrupt the background thread executing the current task, if any.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, run, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

heap_

protected final PriorityBlockingQueue<com.cosylab.epics.caj.util.Timer.TaskNode> heap_

Tasks are maintained in a standard priority queue.

thread_

protected Thread thread_

The thread used to process commands

runLoop_

protected final Timer.RunLoop runLoop_

Constructor Detail

Timer

public Timer()

Protected constructor (singleton pattern).

Method Detail

executeAfterDelay

public Object executeAfterDelay(long millisecondsToDelay,
                                Timer.TimerRunnable command)

Excecute the given command after waiting for the given delay.

Parameters:

millisecondsToDelay - -- the number of milliseconds from now to run the command.

command - -- the command to run after the delay.

Returns:

taskID -- an opaque reference that can be used to cancel execution request

executePeriodically

public Object executePeriodically(long period,
                                  Timer.TimerRunnable command,
                                  long firstTime)

Execute the given command every period milliseconds AT FIXED RATE. If startNow is true, execution begins immediately, otherwise, it begins after the first period delay.

Parameters:

period - -- the period, in milliseconds. Periods are measured from start-of-task to the next start-of-task. It is generally a bad idea to use a period that is shorter than the expected task duration.

command - -- the command to run at each cycle

firstTime - -- time when task should start with execution, 0 means immediately.

Returns:

taskID -- an opaque reference that can be used to cancel execution request

Throws:

IllegalArgumentException - if period less than or equal to zero.

cancel

public static void cancel(Object taskID)

Cancel a scheduled task that has not yet been run. The task will be cancelled upon the next opportunity to run it. This has no effect if this is a one-shot task that has already executed. Also, if an execution is in progress, it will complete normally. (It may however be interrupted via getThread().interrupt()). But if it is a periodic task, future iterations are cancelled.

Parameters:

taskID - -- a task reference returned by one of the execute commands

Throws:

ClassCastException - if the taskID argument is not of the type returned by an execute command.

clearThread

protected void clearThread()

set thread_ to null to indicate termination

restart

public void restart()

Start (or restart) a thread to process commands, or wake up an existing thread if one is already running. This method can be invoked if the background thread crashed due to an unrecoverable exception in an executed command.

shutDown

public void shutDown()

Cancel all tasks and interrupt the background thread executing the current task, if any. A new background thread will be started if new execution requests are encountered. If the currently executing task does not repsond to interrupts, the current thread may persist, even if a new thread is started via restart().

nextTask

protected com.cosylab.epics.caj.util.Timer.TaskNode nextTask()

Return the next task to execute, or null if thread is interrupted.