1.概述
Timer进行一个完整的定时任务需要结合TimerTask类一起使用。
Timer：是JDK提供的一个定时器工具，使用时会在主线程之外开启一个单独的线程用于执行指定的计划任务。可安排任务执行一次（延迟执行）或者定期重复执行多次。
TimerTask：是一个实现了Runnable接口的抽象类，代表一个可以被Timer执行的任务。
我们可以这样理解，Timer是一个定时调度工具，TimerTask是一个指定的任务。需要定时循环一次或多次完成一个任务时，由Timer调度Timer完成这项任务。Timer是一个调度员，TimerTask代表的是具体任务。
2.Timer类中的6种构造方法：
1).schedule(TimerTask task, Date time)：安排任务在指定时间time执行一次任务；
2).schedule(TimerTask task, Date firstTime, long period) ：安排任务在指定时间firstTime开始以固定间隔period重复执行任务；
3).schedule(TimerTask task, long delay)：安排任务在指定延迟delay秒后执行，只执行一次
4).schedule(TimerTask task, long delay, long period)：安排任务从指定的延迟delay秒后以固定间隔period重复执行任务
5).scheduleAtFixedRate(TimerTask task, Date firstTime, long period)：安排任务在指定时间firstTime开始以固定速率（period秒)重复执行任务
6).scheduleAtFixedRate(TimerTask task, long delay, long period)：安排任务在指定的延迟delay秒后开始以固定速率(period秒)重复执行任务
文章末尾有Timer源码。
3.注意事项
3.1 关于时间间隔period的问题。这里仅仅说明 schedule 中的时间间隔 period。schedule 中的period是紧邻的两次任务的实际执行时间的时间差，并不是上次任务执行结束时间与下次任务的实际执行开始时间的时间差，所以理论上讲，如果执行任务的总耗时 totlaTime < period 时，period = 下次任务实际执行时间 - 上次任务实际执行时间。如果执行任务的总耗时 totalTime > period 时，下次任务的执行时间就是上次任务的结束时间，中间没有间隔。如果period为0，则任务只执行一次。
3.2 关于time，firstTime的问题，构造方法 1)，2)，5) 中都指定了任务的开始时间为time，如果time < systemCurrentTime，该定时任务会立即开始执行，如果time > systemCurrentTime，该定时任务到了指定的time时才执行。
3.3 源码解释
* <p>In fixed-delay execution, each execution is scheduled relative to
* the actual execution time of the previous execution. If an execution
* is delayed for any reason (such as garbage collection or other
* background activity), subsequent executions will be delayed as well.
* In the long run, the frequency of execution will generally be slightly
* lower than the reciprocal of the specified period (assuming the system
* clock underlying <tt>Object.wait(long)</tt> is accurate). As a
* consequence of the above, if the scheduled first time is in the past,
* it is scheduled for immediate execution.
public void schedule(TimerTask task, Date firstTime, long period) {
if (period <= 0)
throw new IllegalArgumentException("Non-positive period.");
sched(task, firstTime.getTime(), -period);
}
翻译为中文的大概意思
* 在固定延迟执行中，每次执行都是相对于前一次执行的实际执行时间来安排的。
* 如果由于任何原因(如垃圾收集或其他后台活动)执行被延迟，后续的执行也会被延迟。
* 从长远来看，执行的频率通常会略低于指定周期的倒数(假设< tt>Object.wait(long)</tt>
* 的系统时钟是准确的)。由于上述原因，如果计划的第一次是过去的，则计划立即执行
4.schedule与scheduleAtFixedRate的区别
从构造方法上的区别主要是scheduleAtFixedRate后面多了FixedRate，翻译为中文就是“固定速率”。
2)和5)的区别：
2)是以固定延迟执行任务，5)是以固定速率执行任务，2)重复执行任务的过程中上一个任务的执行耗时会影响下一 个任务的执行时间，可以理解为串联执行任务；上一个任务执行完毕后，如果当前时间-上次任务执行时间>任务间隔时间， 则下一次任务立即执行（上次任务的完成时间就是下次任务的执行时间），如果当前时间-上次任务执行时间<任务间隔时 间，则下次任务在 上次任务执行时间+任务间隔时间后开始执行。测试结果见测试2，4，7，8。
5)重复执行任务的过程中上一个任务的执行耗时不会影响一个任务的执行时间。每次任务的执行时间都是在第一次任务开始的时间戳上加上 (n-1)*时间间隔 。测试结果见栗子5，6，9，10.
4)和6)的区别同上。
具体的区别见6测试结果总结。
5.测试结果分析
创建任务Timer：
Timer timer = new Timer();创建TimerTask:
TimerTask task = new TimerTask() {
@Override
public void run() {
System.out.println("任务执行时间1：" + this.scheduledExecutionTime());
testRun(200000);
/*try {
Thread.sleep(2000);
} catch (InterruptedException e) {
e.printStackTrace();
}*/
// this.cancel(); // 将该任务从任务队列中清除
// timer.cancel(); // 清除任务队列中的全部任务
// TimerTask.cancel() 和 Timer.cancel() 是有区别的，使用过程中需要注意。
// java.util.TimerTask.scheduledExecutionTime() 方法用于返回此任务最近实际执行的安排执行的时间
}
};java.util.TimerTask.scheduledExecutionTime() 方法用于返回此任务最近实际安排执行的时间.
TimerTask.cancel() 与 Timer.cancel() 区别见另一篇文章 Timer.cancel() 与 TimerTask.cancel()的区别.
创建testRun()
public static void testRun(int times) {
System.err.println("任务开始时间2：" + System.currentTimeMillis());
for (int i = 0; i < times; i++) {
String str = "111";
str += "222";
str += "333";
str += "444";
str += "555";
}
System.err.println("任务完成时间3：" + System.currentTimeMillis());
}先测试times = 200000 时 testRun()的运行时间，测试结果为
任务开始时间2：1547909480928
任务完成时间3：1547909481006
任务开始时间2：1547909491097
任务完成时间3：1547909491172
任务开始时间2：1547909503956
任务完成时间3：1547909504027多次测试后，testRun()每次的运行时长大约为 70ms
测试1和测试6主要测试任务时长小于任务间隔时间的情况
测试1：TimerTask.schedule(TimerTask task, Date time)
Date date = sdf.parse("2019-01-19 22:57:30");
timer.schedule(task, date);测试结果
任务执行时间1：1547909850000
任务开始时间2：1547909850001
任务完成时间3：1547909850092测试2：TimerTask.schedule(TimerTask task, Date firstTime, long period)
Date date = sdf.parse("2019-01-19 22:59:15");
long period = 1000; // 任务间隔毫秒数
timer.schedule(task, date, period);测试结果：
任务执行时间1：1547909955000
任务开始时间2：1547909955004
任务完成时间3：1547909955081
任务执行时间1：1547909956001
任务开始时间2：1547909956001
任务完成时间3：1547909956038
任务执行时间1：1547909957002
任务开始时间2：1547909957002
任务完成时间3：1547909957026
任务执行时间1：1547909958002
任务开始时间2：1547909958002
任务完成时间3：1547909958045
任务执行时间1：1547909959003
任务开始时间2：1547909959003
任务完成时间3：1547909959034测试结果分析：
从测试结果我们可以看出，当任务执行时长小于任务间隔时间时，每次任务之间的间隔时间大约都是1000ms。相差的几个毫秒是由于当前这个线程在执行垃圾回收等等其它任务造成任务的延迟。
测试3：TimerTask.schedule(TimerTask task, long delay)
long delay = 1000; // 任务延迟毫秒数
timer.schedule(task, delay);测试结果
任务执行时间1：1547910433033
任务开始时间2：1547910433033
任务完成时间3：1547910433111测试4：TimerTask.schedule(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.schedule(task, delay, period);测试结果
任务执行时间1：1547910927695
任务开始时间2：1547910927695
任务完成时间3：1547910927745
任务执行时间1：1547910928699
任务开始时间2：1547910928699
任务完成时间3：1547910928733
任务执行时间1：1547910929699
任务开始时间2：1547910929699
任务完成时间3：1547910929715
任务执行时间1：1547910930702
任务开始时间2：1547910930702
任务完成时间3：1547910930735从测试结果我们可以看出，当任务执行时长小于任务间隔时间时，每次任务之间的间隔时间大约都是1000ms。相差的几个毫秒是由于当前这个线程在执行垃圾回收等等其它任务造成任务的延迟。
测试5：TimerTask.scheduleAtFixedRate(TimerTask task, Date firstTime, long period)
Date date = sdf.parse("2019-01-19 22:59:15");
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, date, period);测试结果
任务执行时间1：1547911150000
任务开始时间2：1547911150008
任务完成时间3：1547911150074
任务执行时间1：1547911151000
任务开始时间2：1547911151009
任务完成时间3：1547911151042
任务执行时间1：1547911152000
任务开始时间2：1547911152011
任务完成时间3：1547911152029
任务执行时间1：1547911153000
任务开始时间2：1547911153007
任务完成时间3：1547911153038测试结果分析：
从测试结果我们可以看出，当任务执行时长小于任务间隔时间时，每次任务之间的间隔时间都是绝对的1000ms。每次到了任务的预定时间就开始执行下次任务。
测试6：TimerTask.scheduleAtFixedRate(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, delay, period);测试结果
任务执行时间1：1547911834883
任务开始时间2：1547911834898
任务完成时间3：1547911834964
任务执行时间1：1547911835883
任务开始时间2：1547911835897
任务完成时间3：1547911835928
任务执行时间1：1547911836883
任务开始时间2：1547911836890
任务完成时间3：1547911836908测试结果分析：
从测试结果我们可以看出，当任务执行时长小于任务间隔时间时，每次任务之间的间隔时间都是绝对的1000ms。每次到了任务的预定时间就开始执行下次任务。
接下来，将 times 改为 20000000，测试下 times = 20000000 时testRun()的运行时间，测试结果为
任务开始时间2：1547908475998
任务完成时间3：1547908478588
任务开始时间2：1547908568611
任务完成时间3：1547908571142
任务开始时间2：1547908598520
任务完成时间3：1547908601113多次测试后，testRun()每次的运行时长大约为 2500ms.
测试7和测试10主要测试任务时长大于任务间隔时间的情况
测试7：TimerTask.schedule(TimerTask task, Date firstTime, long period)
Date date = sdf.parse("2019-01-19 23:33:55");
long period = 1000; // 任务间隔毫秒数
timer.schedule(task, date, period)测试结果
任务执行时间1：1547912035015
任务开始时间2：1547912035015
任务完成时间3：1547912037308
任务执行时间1：1547912037308
任务开始时间2：1547912037308
任务完成时间3：1547912039287
任务执行时间1：1547912039287
任务开始时间2：1547912039287
任务完成时间3：1547912041319测试结果分析：
从测试结果可以看出，当任务执行时长大于任务间隔时间时，上次任务执行结束后忽略掉判断是否执行下次任务的耗时，可以认为上次任务执行结束后下次任务会立即执行。
测试8：TimerTask.schedule(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.schedule(task, delay, period);测试结果
任务执行时间1：1547912515452
任务开始时间2：1547912515452
任务完成时间3：1547912517670
任务执行时间1：1547912517670
任务开始时间2：1547912517670
任务完成时间3：1547912519671
任务执行时间1：1547912519671
任务开始时间2：1547912519671
任务完成时间3：1547912521665
任务执行时间1：1547912521665
任务开始时间2：1547912521665
任务完成时间3：1547912523656从测试结果可以看出，当任务执行时长大于任务间隔时间时，上次任务执行结束后忽略掉判断是否执行下次任务的耗时，可以认为上次任务执行结束后下次任务会立即执行。
测试9：TimerTask.scheduleAtFixedRate(TimerTask task, Date firstTime, long period)
Date date = sdf.parse("2019-01-19 23:44:35")
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, date, period);测试结果
任务开始时间2：1547912675002
任务执行时间1：1547912675000
任务完成时间3：1547912677359
任务执行时间1：1547912676000
任务开始时间2：1547912677359
任务完成时间3：1547912679409
任务执行时间1：1547912677000
任务开始时间2：1547912679409
任务完成时间3：1547912681662
任务执行时间1：1547912678000
任务开始时间2：1547912681663
任务完成时间3：1547912683893测试结果分析：
从测试结果可以看出，当任务执行时长大于任务间隔时间时，每次任务执行时间间隔差都是1000ms，下次任务的执行时间不受上次任务的执行结束时间影响。所以叫固定频率执行任务。
测试10：TimerTask.scheduleAtFixedRate(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, delay, period);测试结果
任务执行时间1：1547913408826
任务开始时间2：1547913408829
任务完成时间3：1547913411057
任务执行时间1：1547913409826
任务开始时间2：1547913411057
任务完成时间3：1547913413039
任务执行时间1：1547913410826
任务开始时间2：1547913413039
任务完成时间3：1547913415014
任务执行时间1：1547913411826
任务开始时间2：1547913415014
任务完成时间3：1547913416982测试结果分析：
从测试结果可以看出，当任务执行时长大于任务间隔时间时，每次任务执行时间间隔差都是1000ms，下次任务的执行时间不受上次任务的执行结束时间影响。所以叫固定频率执行任务。
6.测试结果总结
从测试2，4，7，8结果我们可以看出，Timer.schedule() 构造方法，当任务执行时长小于任务间隔时间时，上次任务执行结束后，下次任务的执行时间与上次任务的执行时间的间隔（忽略掉判断是否执行的时间及其它时间）基本都是period。当任务执行时间大于任务间隔时间时，上次任务执行结束后，下次任务会立即执行（忽略掉判断是否执行的时间及其它时间）。
从测试5，6，9，10结果我们可以看出，Timer.scheduleAtFixedRate() 构造方法，前后任务的执行时间间隔都是绝对的period，任务的执行时长不影响下次任务的正常执行。
总结：
我们可以将schedule想象成是一个没有计划的童鞋，走一步看一步，如果schedule今天的任务提前完成了，明天继续完成明天的任务，如果schedule今天的任务因为有事拖延了，明天schedule会先完成昨天剩余的任务再完成当天的任务。所以schedule侧重于当前任务是否已经完成，每次只执行一个任务。
而我们可以把scheduleAtFixedRate想象成一个有计划的童鞋，scheduleAtFixedRate每天定点开始执行当天的任务，如果昨天的任务还没有完成，那么当天scheduleAtFixedRate会同时执行昨天和今天的任务。所以scheduleAtFixedRate侧重于任务是否定时开始，不考虑任务是否已经完成，如果任务没有完成，那么两个任务会同时进行。
注意点
当使用scheduleAtFixedRate我们需要考虑线程安全问题，因为同一个事务可能会被同时执行。
本文纯个人手写，都是根据个人理解写的，如有错误之处欢迎评论区留言指正。
7.完整Timer源码：
/*
* Copyright (c) 1999, 2008, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*/
package java.util;
import java.util.Date;
import java.util.concurrent.atomic.AtomicInteger;
/**
* A facility for threads to schedule tasks for future execution in a
* background thread. Tasks may be scheduled for one-time execution, or for
* repeated execution at regular intervals.
*
* <p>Corresponding to each <tt>Timer</tt> object is a single background
* thread that is used to execute all of the timer's tasks, sequentially.
* 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.
*
* <p>After the last live reference to a <tt>Timer</tt> object goes away
* <i>and</i> all outstanding tasks have completed execution, the timer's task
* execution thread terminates gracefully (and becomes subject to garbage
* collection). However, this can take arbitrarily long to occur. By
* default, the task execution thread does not run as a <i>daemon thread</i>,
* so it is capable of keeping an application from terminating. If a caller
* wants to terminate a timer's task execution thread rapidly, the caller
* should invoke the timer's <tt>cancel</tt> method.
*
* <p>If the timer's task execution thread terminates unexpectedly, for
* example, because its <tt>stop</tt> method is invoked, any further
* attempt to schedule a task on the timer will result in an
* <tt>IllegalStateException</tt>, as if the timer's <tt>cancel</tt>
* method had been invoked.
*
* <p>This class is thread-safe: multiple threads can share a single
* <tt>Timer</tt> object without the need for external synchronization.
*
* <p>This class does <i>not</i> offer real-time guarantees: it schedules
* tasks using the <tt>Object.wait(long)</tt> method.
*
* <p>Java 5.0 introduced the {@code java.util.concurrent} package and
* one of the concurrency utilities therein is the {@link
* java.util.concurrent.ScheduledThreadPoolExecutor
* ScheduledThreadPoolExecutor} which is a thread pool for repeatedly
* executing tasks at a given rate or delay. It is effectively a more
* versatile replacement for the {@code Timer}/{@code TimerTask}
* combination, as it allows multiple service threads, accepts various
* time units, and doesn't require subclassing {@code TimerTask} (just
* implement {@code Runnable}). Configuring {@code
* ScheduledThreadPoolExecutor} with one thread makes it equivalent to
* {@code Timer}.
*
* <p>Implementation note: This class scales to large numbers of concurrently
* scheduled tasks (thousands should present no problem). Internally,
* it uses a binary heap to represent its task queue, so the cost to schedule
* a task is O(log n), where n is the number of concurrently scheduled tasks.
*
* <p>Implementation note: All constructors start a timer thread.
*
* @author Josh Bloch
* @see TimerTask
* @see Object#wait(long)
* @since 1.3
*/
public class Timer {
/**
* The timer task queue. This data structure is shared with the timer
* thread. The timer produces tasks, via its various schedule calls,
* and the timer thread consumes, executing timer tasks as appropriate,
* and removing them from the queue when they're obsolete.
*/
private final TaskQueue queue = new TaskQueue();
/**
* The timer thread.
*/
private final TimerThread thread = new TimerThread(queue);
/**
* This object causes the timer's task execution thread to exit
* gracefully when there are no live references to the Timer object and no
* tasks in the timer queue. It is used in preference to a finalizer on
* Timer as such a finalizer would be susceptible to a subclass's
* finalizer forgetting to call it.
*/
private final Object threadReaper = new Object() {
protected void finalize() throws Throwable {
synchronized(queue) {
thread.newTasksMayBeScheduled = false;
queue.notify(); // In case queue is empty.
}
}
};
/**
* This ID is used to generate thread names.
*/
private final static AtomicInteger nextSerialNumber = new AtomicInteger(0);
private static int serialNumber() {
return nextSerialNumber.getAndIncrement();
}
/**
* Creates a new timer. The associated thread does <i>not</i>
* {@linkplain Thread#setDaemon run as a daemon}.
*/
public Timer() {
this("Timer-" + serialNumber());
}
/**
* Creates a new timer whose associated thread may be specified to
* {@linkplain Thread#setDaemon run as a daemon}.
* A daemon thread is called for if the timer will be used to
* schedule repeating "maintenance activities", which must be
* performed as long as the application is running, but should not
* prolong the lifetime of the application.
*
* @param isDaemon true if the associated thread should run as a daemon.
*/
public Timer(boolean isDaemon) {
this("Timer-" + serialNumber(), isDaemon);
}
/**
* Creates a new timer whose associated thread has the specified name.
* The associated thread does <i>not</i>
* {@linkplain Thread#setDaemon run as a daemon}.
*
* @param name the name of the associated thread
* @throws NullPointerException if {@code name} is null
* @since 1.5
*/
public Timer(String name) {
thread.setName(name);
thread.start();
}
/**
* Creates a new timer whose associated thread has the specified name,
* and may be specified to
* {@linkplain Thread#setDaemon run as a daemon}.
*
* @param name the name of the associated thread
* @param isDaemon true if the associated thread should run as a daemon
* @throws NullPointerException if {@code name} is null
* @since 1.5
*/
public Timer(String name, boolean isDaemon) {
thread.setName(name);
thread.setDaemon(isDaemon);
thread.start();
}
/**
* Schedules the specified task for execution after the specified delay.
*
* @param task task to be scheduled.
* @param delay delay in milliseconds before task is to be executed.
* @throws IllegalArgumentException if <tt>delay</tt> is negative, or
* <tt>delay + System.currentTimeMillis()</tt> is negative.
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} is null
*/
public void schedule(TimerTask task, long delay) {
if (delay < 0)
throw new IllegalArgumentException("Negative delay.");
sched(task, System.currentTimeMillis()+delay, 0);
}
/**
* Schedules the specified task for execution at the specified time. If
* the time is in the past, the task is scheduled for immediate execution.
*
* @param task task to be scheduled.
* @param time time at which task is to be executed.
* @throws IllegalArgumentException if <tt>time.getTime()</tt> is negative.
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} or {@code time} is null
*/
public void schedule(TimerTask task, Date time) {
sched(task, time.getTime(), 0);
}
/**
* Schedules the specified task for repeated <i>fixed-delay execution</i>,
* beginning after the specified delay. Subsequent executions take place
* at approximately regular intervals separated by the specified period.
*
* <p>In fixed-delay execution, each execution is scheduled relative to
* the actual execution time of the previous execution. If an execution
* is delayed for any reason (such as garbage collection or other
* background activity), subsequent executions will be delayed as well.
* In the long run, the frequency of execution will generally be slightly
* lower than the reciprocal of the specified period (assuming the system
* clock underlying <tt>Object.wait(long)</tt> is accurate).
*
* <p>Fixed-delay execution is appropriate for recurring activities
* that require "smoothness." In other words, it is appropriate for
* activities where it is more important to keep the frequency accurate
* in the short run than in the long run. This includes most animation
* tasks, such as blinking a cursor at regular intervals. It also includes
* tasks wherein regular activity is performed in response to human
* input, such as automatically repeating a character as long as a key
* is held down.
*
* @param task task to be scheduled.
* @param delay delay in milliseconds before task is to be executed.
* @param period time in milliseconds between successive task executions.
* @throws IllegalArgumentException if {@code delay < 0}, or
* {@code delay + System.currentTimeMillis() < 0}, or
* {@code period <= 0}
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} is null
*/
public void schedule(TimerTask task, long delay, long period) {
if (delay < 0)
throw new IllegalArgumentException("Negative delay.");
if (period <= 0)
throw new IllegalArgumentException("Non-positive period.");
sched(task, System.currentTimeMillis()+delay, -period);
}
/**
* Schedules the specified task for repeated <i>fixed-delay execution</i>,
* beginning at the specified time. Subsequent executions take place at
* approximately regular intervals, separated by the specified period.
*
* <p>In fixed-delay execution, each execution is scheduled relative to
* the actual execution time of the previous execution. If an execution
* is delayed for any reason (such as garbage collection or other
* background activity), subsequent executions will be delayed as well.
* In the long run, the frequency of execution will generally be slightly
* lower than the reciprocal of the specified period (assuming the system
* clock underlying <tt>Object.wait(long)</tt> is accurate). As a
* consequence of the above, if the scheduled first time is in the past,
* it is scheduled for immediate execution.
*
* <p>Fixed-delay execution is appropriate for recurring activities
* that require "smoothness." In other words, it is appropriate for
* activities where it is more important to keep the frequency accurate
* in the short run than in the long run. This includes most animation
* tasks, such as blinking a cursor at regular intervals. It also includes
* tasks wherein regular activity is performed in response to human
* input, such as automatically repeating a character as long as a key
* is held down.
*
* @param task task to be scheduled.
* @param firstTime First time at which task is to be executed.
* @param period time in milliseconds between successive task executions.
* @throws IllegalArgumentException if {@code firstTime.getTime() < 0}, or
* {@code period <= 0}
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} or {@code firstTime} is null
*/
public void schedule(TimerTask task, Date firstTime, long period) {
if (period <= 0)
throw new IllegalArgumentException("Non-positive period.");
sched(task, firstTime.getTime(), -period);
}
/**
* Schedules the specified task for repeated <i>fixed-rate execution</i>,
* beginning after the specified delay. Subsequent executions take place
* at approximately regular intervals, separated by the specified period.
*
* <p>In fixed-rate execution, each execution is scheduled relative to the
* scheduled execution time of the initial execution. If an execution is
* delayed for any reason (such as garbage collection or other background
* activity), two or more executions will occur in rapid succession to
* "catch up." In the long run, the frequency of execution will be
* exactly the reciprocal of the specified period (assuming the system
* clock underlying <tt>Object.wait(long)</tt> is accurate).
*
* <p>Fixed-rate execution is appropriate for recurring activities that
* are sensitive to <i>absolute</i> time, such as ringing a chime every
* hour on the hour, or running scheduled maintenance every day at a
* particular time. It is also appropriate for recurring activities
* where the total time to perform a fixed number of executions is
* important, such as a countdown timer that ticks once every second for
* ten seconds. Finally, fixed-rate execution is appropriate for
* scheduling multiple repeating timer tasks that must remain synchronized
* with respect to one another.
*
* @param task task to be scheduled.
* @param delay delay in milliseconds before task is to be executed.
* @param period time in milliseconds between successive task executions.
* @throws IllegalArgumentException if {@code delay < 0}, or
* {@code delay + System.currentTimeMillis() < 0}, or
* {@code period <= 0}
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} is null
*/
public void scheduleAtFixedRate(TimerTask task, long delay, long period) {
if (delay < 0)
throw new IllegalArgumentException("Negative delay.");
if (period <= 0)
throw new IllegalArgumentException("Non-positive period.");
sched(task, System.currentTimeMillis()+delay, period);
}
/**
* Schedules the specified task for repeated <i>fixed-rate execution</i>,
* beginning at the specified time. Subsequent executions take place at
* approximately regular intervals, separated by the specified period.
*
* <p>In fixed-rate execution, each execution is scheduled relative to the
* scheduled execution time of the initial execution. If an execution is
* delayed for any reason (such as garbage collection or other background
* activity), two or more executions will occur in rapid succession to
* "catch up." In the long run, the frequency of execution will be
* exactly the reciprocal of the specified period (assuming the system
* clock underlying <tt>Object.wait(long)</tt> is accurate). As a
* consequence of the above, if the scheduled first time is in the past,
* then any "missed" executions will be scheduled for immediate "catch up"
* execution.
*
* <p>Fixed-rate execution is appropriate for recurring activities that
* are sensitive to <i>absolute</i> time, such as ringing a chime every
* hour on the hour, or running scheduled maintenance every day at a
* particular time. It is also appropriate for recurring activities
* where the total time to perform a fixed number of executions is
* important, such as a countdown timer that ticks once every second for
* ten seconds. Finally, fixed-rate execution is appropriate for
* scheduling multiple repeating timer tasks that must remain synchronized
* with respect to one another.
*
* @param task task to be scheduled.
* @param firstTime First time at which task is to be executed.
* @param period time in milliseconds between successive task executions.
* @throws IllegalArgumentException if {@code firstTime.getTime() < 0} or
* {@code period <= 0}
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} or {@code firstTime} is null
*/
public void scheduleAtFixedRate(TimerTask task, Date firstTime,
long period) {
if (period <= 0)
throw new IllegalArgumentException("Non-positive period.");
sched(task, firstTime.getTime(), period);
}
/**
* Schedule the specified timer task for execution at the specified
* time with the specified period, in milliseconds. If period is
* positive, the task is scheduled for repeated execution; if period is
* zero, the task is scheduled for one-time execution. Time is specified
* in Date.getTime() format. This method checks timer state, task state,
* and initial execution time, but not period.
*
* @throws IllegalArgumentException if <tt>time</tt> is negative.
* @throws IllegalStateException if task was already scheduled or
* cancelled, timer was cancelled, or timer thread terminated.
* @throws NullPointerException if {@code task} is null
*/
private void sched(TimerTask task, long time, long period) {
if (time < 0)
throw new IllegalArgumentException("Illegal execution time.");
// Constrain value of period sufficiently to prevent numeric
// overflow while still being effectively infinitely large.
if (Math.abs(period) > (Long.MAX_VALUE >> 1))
period >>= 1;
synchronized(queue) {
if (!thread.newTasksMayBeScheduled)
throw new IllegalStateException("Timer already cancelled.");
synchronized(task.lock) {
if (task.state != TimerTask.VIRGIN)
throw new IllegalStateException(
"Task already scheduled or cancelled");
task.nextExecutionTime = time;
task.period = period;
task.state = TimerTask.SCHEDULED;
}
queue.add(task);
if (queue.getMin() == task)
queue.notify();
}
}
/**
* Terminates this timer, discarding any currently scheduled tasks.
* Does not interfere with a currently executing task (if it exists).
* Once a timer has been terminated, its execution thread terminates
* gracefully, and no more tasks may be scheduled on it.
*
* <p>Note that calling this method from within the run method of a
* timer task that was invoked by this timer absolutely guarantees that
* the ongoing task execution is the last task execution that will ever
* be performed by this timer.
*
* <p>This method may be called repeatedly; the second and subsequent
* calls have no effect.
*/
public void cancel() {
synchronized(queue) {
thread.newTasksMayBeScheduled = false;
queue.clear();
queue.notify(); // In case queue was already empty.
}
}
/**
* Removes all cancelled tasks from this timer's task queue. <i>Calling
* this method has no effect on the behavior of the timer</i>, but
* eliminates the references to the cancelled tasks from the queue.
* If there are no external references to these tasks, they become
* eligible for garbage collection.
*
* <p>Most programs will have no need to call this method.
* It is designed for use by the rare application that cancels a large
* number of tasks. Calling this method trades time for space: the
* runtime of the method may be proportional to n + c log n, where n
* is the number of tasks in the queue and c is the number of cancelled
* tasks.
*
* <p>Note that it is permissible to call this method from within a
* a task scheduled on this timer.
*
* @return the number of tasks removed from the queue.
* @since 1.5
*/
public int purge() {
int result = 0;
synchronized(queue) {
for (int i = queue.size(); i > 0; i--) {
if (queue.get(i).state == TimerTask.CANCELLED) {
queue.quickRemove(i);
result++;
}
}
if (result != 0)
queue.heapify();
}
return result;
}
}
/**
* This "helper class" implements the timer's task execution thread, which
* waits for tasks on the timer queue, executions them when they fire,
* reschedules repeating tasks, and removes cancelled tasks and spent
* non-repeating tasks from the queue.
*/
class TimerThread extends Thread {
/**
* This flag is set to false by the reaper to inform us that there
* are no more live references to our Timer object. Once this flag
* is true and there are no more tasks in our queue, there is no
* work left for us to do, so we terminate gracefully. Note that
* this field is protected by queue's monitor!
*/
boolean newTasksMayBeScheduled = true;
/**
* Our Timer's queue. We store this reference in preference to
* a reference to the Timer so the reference graph remains acyclic.
* Otherwise, the Timer would never be garbage-collected and this
* thread would never go away.
*/
private TaskQueue queue;
TimerThread(TaskQueue queue) {
this.queue = queue;
}
public void run() {
try {
mainLoop();
} finally {
// Someone killed this Thread, behave as if Timer cancelled
synchronized(queue) {
newTasksMayBeScheduled = false;
queue.clear(); // Eliminate obsolete references
}
}
}
/**
* The main timer loop. (See class comment.)
*/
private void mainLoop() {
while (true) {
try {
TimerTask task;
boolean taskFired;
synchronized(queue) {
// Wait for queue to become non-empty
while (queue.isEmpty() && newTasksMayBeScheduled)
queue.wait();
if (queue.isEmpty())
break; // Queue is empty and will forever remain; die
// Queue nonempty; look at first evt and do the right thing
long currentTime, executionTime;
task = queue.getMin();
synchronized(task.lock) {
if (task.state == TimerTask.CANCELLED) {
queue.removeMin();
continue; // No action required, poll queue again
}
currentTime = System.currentTimeMillis();
executionTime = task.nextExecutionTime;
if (taskFired = (executionTime<=currentTime)) {
if (task.period == 0) { // Non-repeating, remove
queue.removeMin();
task.state = TimerTask.EXECUTED;
} else { // Repeating task, reschedule
queue.rescheduleMin(
task.period<0 ? currentTime - task.period
: executionTime + task.period);
}
}
}
if (!taskFired) // Task hasn't yet fired; wait
queue.wait(executionTime - currentTime);
}
if (taskFired) // Task fired; run it, holding no locks
task.run();
} catch(InterruptedException e) {
}
}
}
}
/**
* This class represents a timer task queue: a priority queue of TimerTasks,
* ordered on nextExecutionTime. Each Timer object has one of these, which it
* shares with its TimerThread. Internally this class uses a heap, which
* offers log(n) performance for the add, removeMin and rescheduleMin
* operations, and constant time performance for the getMin operation.
*/
class TaskQueue {
/**
* Priority queue represented as a balanced binary heap: the two children
* of queue[n] are queue[2*n] and queue[2*n+1]. The priority queue is
* ordered on the nextExecutionTime field: The TimerTask with the lowest
* nextExecutionTime is in queue[1] (assuming the queue is nonempty). For
* each node n in the heap, and each descendant of n, d,
* n.nextExecutionTime <= d.nextExecutionTime.
*/
private TimerTask[] queue = new TimerTask[128];
/**
* The number of tasks in the priority queue. (The tasks are stored in
* queue[1] up to queue[size]).
*/
private int size = 0;
/**
* Returns the number of tasks currently on the queue.
*/
int size() {
return size;
}
/**
* Adds a new task to the priority queue.
*/
void add(TimerTask task) {
// Grow backing store if necessary
if (size + 1 == queue.length)
queue = Arrays.copyOf(queue, 2*queue.length);
queue[++size] = task;
fixUp(size);
}
/**
* Return the "head task" of the priority queue. (The head task is an
* task with the lowest nextExecutionTime.)
*/
TimerTask getMin() {
return queue[1];
}
/**
* Return the ith task in the priority queue, where i ranges from 1 (the
* head task, which is returned by getMin) to the number of tasks on the
* queue, inclusive.
*/
TimerTask get(int i) {
return queue[i];
}
/**
* Remove the head task from the priority queue.
*/
void removeMin() {
queue[1] = queue[size];
queue[size--] = null; // Drop extra reference to prevent memory leak
fixDown(1);
}
/**
* Removes the ith element from queue without regard for maintaining
* the heap invariant. Recall that queue is one-based, so
* 1 <= i <= size.
*/
void quickRemove(int i) {
assert i <= size;
queue[i] = queue[size];
queue[size--] = null; // Drop extra ref to prevent memory leak
}
/**
* Sets the nextExecutionTime associated with the head task to the
* specified value, and adjusts priority queue accordingly.
*/
void rescheduleMin(long newTime) {
queue[1].nextExecutionTime = newTime;
fixDown(1);
}
/**
* Returns true if the priority queue contains no elements.
*/
boolean isEmpty() {
return size==0;
}
/**
* Removes all elements from the priority queue.
*/
void clear() {
// Null out task references to prevent memory leak
for (int i=1; i<=size; i++)
queue[i] = null;
size = 0;
}
/**
* Establishes the heap invariant (described above) assuming the heap
* satisfies the invariant except possibly for the leaf-node indexed by k
* (which may have a nextExecutionTime less than its parent's).
*
* This method functions by "promoting" queue[k] up the hierarchy
* (by swapping it with its parent) repeatedly until queue[k]'s
* nextExecutionTime is greater than or equal to that of its parent.
*/
private void fixUp(int k) {
while (k > 1) {
int j = k >> 1;
if (queue[j].nextExecutionTime <= queue[k].nextExecutionTime)
break;
TimerTask tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp;
k = j;
}
}
/**
* Establishes the heap invariant (described above) in the subtree
* rooted at k, which is assumed to satisfy the heap invariant except
* possibly for node k itself (which may have a nextExecutionTime greater
* than its children's).
*
* This method functions by "demoting" queue[k] down the hierarchy
* (by swapping it with its smaller child) repeatedly until queue[k]'s
* nextExecutionTime is less than or equal to those of its children.
*/
private void fixDown(int k) {
int j;
while ((j = k << 1) <= size && j > 0) {
if (j < size &&
queue[j].nextExecutionTime > queue[j+1].nextExecutionTime)
j++; // j indexes smallest kid
if (queue[k].nextExecutionTime <= queue[j].nextExecutionTime)
break;
TimerTask tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp;
k = j;
}
}
/**
* Establishes the heap invariant (described above) in the entire tree,
* assuming nothing about the order of the elements prior to the call.
*/
void heapify() {
for (int i = size/2; i >= 1; i--)
fixDown(i);
}
}