EDU.oswego.cs.dl.util.concurrent
public class ClockDaemon extends ThreadFactoryUser
at
(and the associated crond) in Unix.
Objects of this class maintain a single thread and a task queue
that may be used to execute Runnable commands in any of three modes --
absolute (run at a given time), relative (run after a given delay),
and periodic (cyclically run with a given delay).
All commands are executed by the single background thread.
The thread is not actually started until the first
request is encountered. Also, if the
thread is stopped for any reason, one is started upon encountering
the next request, or restart()
is invoked.
If you would instead like commands run in their own threads, you can use as arguments Runnable commands that start their own threads (or perhaps wrap within ThreadedExecutors).
You can also use multiple daemon objects, each using a different background thread. However, one of the reasons for using a time daemon is to pool together processing of infrequent tasks using a single background thread.
Background threads are created using a ThreadFactory. The
default factory does not
automatically setDaemon
status.
The class uses Java timed waits for scheduling. These can vary in precision across platforms, and provide no real-time guarantees about meeting deadlines.
Nested Class Summary | |
---|---|
protected class | ClockDaemon.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.
|
protected static class | ClockDaemon.TaskNode |
Field Summary | |
---|---|
protected Heap | heap_ tasks are maintained in a standard priority queue * |
protected ClockDaemon.RunLoop | runLoop_ |
protected Thread | thread_ The thread used to process commands * |
Constructor Summary | |
---|---|
ClockDaemon()
Create a new ClockDaemon
|
Method Summary | |
---|---|
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, Runnable command)
Excecute the given command after waiting for the given delay.
|
Object | executeAt(Date date, Runnable command)
Execute the given command at the given time. |
Object | executePeriodically(long period, Runnable command, boolean startNow)
Execute the given command every period milliseconds.
|
Thread | getThread()
Return the thread being used to process commands, or
null if there is no such thread. |
protected ClockDaemon.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.
|
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.
Sample Usage. You can use a ClockDaemon to arrange timeout callbacks to break out of stuck IO. For example (code sketch):
class X { ... ClockDaemon timer = ... Thread readerThread; FileInputStream datafile; void startReadThread() { datafile = new FileInputStream("data", ...); readerThread = new Thread(new Runnable() { public void run() { for(;;) { // try to gracefully exit before blocking if (Thread.currentThread().isInterrupted()) { quietlyWrapUpAndReturn(); } else { try { int c = datafile.read(); if (c == -1) break; else process(c); } catch (IOException ex) { cleanup(); return; } } } }; readerThread.start(); // establish callback to cancel after 60 seconds timer.executeAfterDelay(60000, new Runnable() { readerThread.interrupt(); // try to interrupt thread datafile.close(); // force thread to lose its input file }); } }
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
Parameters: date -- the absolute time to run the command, expressed as a java.util.Date. command -- the command to run at the given time.
Returns: taskID -- an opaque reference that can be used to cancel execution request
period
milliseconds.
If startNow
is true, execution begins immediately,
otherwise, it begins after the first period
delay.
Sample Usage. Here is one way to update Swing components acting as progress indicators for long-running actions.
class X { JLabel statusLabel = ...; int percentComplete = 0; synchronized int getPercentComplete() { return percentComplete; } synchronized void setPercentComplete(int p) { percentComplete = p; } ClockDaemon cd = ...; void startWorking() { Runnable showPct = new Runnable() { public void run() { SwingUtilities.invokeLater(new Runnable() { public void run() { statusLabel.setText(getPercentComplete() + "%"); } } } }; final Object updater = cd.executePeriodically(500, showPct, true); Runnable action = new Runnable() { public void run() { for (int i = 0; i < 100; ++i) { work(); setPercentComplete(i); } cd.cancel(updater); } }; new Thread(action).start(); } }
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 startNow -- true if the cycle should start with execution
of the task now. Otherwise, the cycle starts with a delay of
period
milliseconds.
Returns: taskID -- an opaque reference that can be used to cancel execution request
Throws: IllegalArgumentException if period less than or equal to zero.