1 Overview
Timer needs to be used in conjunction with the TimerTask class to perform a complete timing task.
Timer: It is a timer tool provided by JDK. When used, a separate thread will be opened outside the main thread to execute the specified scheduled task. Tasks can be scheduled to execute once (delayed execution) or repeated multiple times at regular intervals.
TimerTask: It is an abstract class that implements the Runnable interface, representing a task that can be executed by Timer.
We can understand that Timer is a timing scheduling tool, and TimerTask is a specified task. When the timing loop needs to complete a task one or more times, the Timer schedules the Timer to complete the task. Timer is a scheduler, and TimerTask represents specific tasks.
2. Six construction methods in the Timer class:
1).schedule(TimerTask task, Date time): Schedule the task to execute a task at the specified time;
2).schedule(TimerTask task, Date firstTime, long period) : schedule the task to repeat the task at a fixed interval period starting at the specified time firstTime;
3).schedule(TimerTask task, long delay): Schedule the task to be executed after the specified delay delay seconds, only once
4).schedule(TimerTask task, long delay, long period): Schedule the task to repeat the task at a fixed interval period after the specified delay delay seconds
5).scheduleAtFixedRate(TimerTask task, Date firstTime, long period): Schedule the task to repeat the task at a fixed rate (period seconds) starting at the specified time firstTime
6).scheduleAtFixedRate(TimerTask task, long delay, long period): Schedule the task to repeat the task at a fixed rate (period seconds) after the specified delay delay seconds
There is Timer source code at the end of the article.
3. Precautions
3.1 Questions about the time interval period . Here only the time interval period in the schedule is explained. The period in the schedule is the time difference between the actual execution time of two adjacent tasks, not the time difference between the end time of the last task execution and the actual execution start time of the next task, so in theory, if the total time spent totlaTime < period, period = the actual execution time of the next task - the actual execution time of the last task . If the total time spent on executing the task totalTime > period, the execution time of the next task is the end time of the last task, with no interval in between . If period is 0, the task will only be executed once.
3.2 Regarding the question of time and firstTime , the construction methods 1), 2), and 5) all specify the start time of the task as time. If time < systemCurrentTime, the scheduled task will start executing immediately. If time > systemCurrentTime, the scheduled task will Executed when the specified time is reached.
3.3 Source code explanation
* <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. The difference between schedule and scheduleAtFixedRate
The difference in the construction method is mainly that there is an additional FixedRate behind scheduleAtFixedRate, which translates to "fixed rate" in Chinese.
The difference between 2) and 5):
2) Executing tasks with a fixed delay, 5) Executing tasks at a fixed rate, 2) In the process of repeatedly executing tasks, the execution time of the previous task will affect the execution time of the next task, which can be understood as executing tasks in series ; After a task is executed, if the current time - last task execution time > task interval time , the next task will be executed immediately (the completion time of the last task is the execution time of the next task), if the current time - last task execution Time < task interval time, then the next task will be executed after the last task execution time + task interval time . See Test 2, 4, 7, 8 for test results.
5) In the process of repeatedly executing tasks, the execution time of the previous task will not affect the execution time of a task. The execution time of each task is to add (n-1)*time interval to the timestamp when the first task starts . See chestnuts 5, 6, 9, and 10 for test results.
The difference between 4) and 6) is the same as above.
For specific differences, see 6 Summary of Test Results.
5. Analysis of test results
Create a task Timer:
Timer timer = new Timer();Create a 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() 方法用于返回此任务最近实际执行的安排执行的时间
}
};The java.util.TimerTask.scheduledExecutionTime() method is used to return the last time this task was actually scheduled for execution.
For the difference between TimerTask.cancel() and Timer.cancel(), see the difference between Timer.cancel() and TimerTask.cancel() in another article .
Create 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());
}First test the running time of testRun() when times = 200000, the test result is
任务开始时间2：1547909480928
任务完成时间3：1547909481006
任务开始时间2：1547909491097
任务完成时间3：1547909491172
任务开始时间2：1547909503956
任务完成时间3：1547909504027After multiple tests, the running time of testRun() is about 70ms each time
Test 1 and Test 6 mainly test the case that the task duration is shorter than the task interval time
测试1：TimerTask.schedule(TimerTask task, Date time)
Date date = sdf.parse("2019-01-19 22:57:30");
timer.schedule(task, date);Test Results
任务执行时间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);Test Results:
任务执行时间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：1547909959034Analysis of test results:
From the test results, we can see that when the task execution time is shorter than the task interval time , the interval time between each task is about 1000ms. The difference of a few milliseconds is due to the delay of the task caused by the current thread performing other tasks such as garbage collection.
测试3：TimerTask.schedule(TimerTask task, long delay)
long delay = 1000; // 任务延迟毫秒数
timer.schedule(task, delay);Test Results
任务执行时间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);Test Results
任务执行时间1：1547910927695
任务开始时间2：1547910927695
任务完成时间3：1547910927745
任务执行时间1：1547910928699
任务开始时间2：1547910928699
任务完成时间3：1547910928733
任务执行时间1：1547910929699
任务开始时间2：1547910929699
任务完成时间3：1547910929715
任务执行时间1：1547910930702
任务开始时间2：1547910930702
任务完成时间3：1547910930735From the test results, we can see that when the task execution time is shorter than the task interval time , the interval time between each task is about 1000ms. The difference of a few milliseconds is due to the delay of the task caused by the current thread performing other tasks such as garbage collection.
Test5： 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);Test Results
任务执行时间1：1547911150000
任务开始时间2：1547911150008
任务完成时间3：1547911150074
任务执行时间1：1547911151000
任务开始时间2：1547911151009
任务完成时间3：1547911151042
任务执行时间1：1547911152000
任务开始时间2：1547911152011
任务完成时间3：1547911152029
任务执行时间1：1547911153000
任务开始时间2：1547911153007
任务完成时间3：1547911153038Analysis of test results:
From the test results, we can see that when the task execution time is shorter than the task interval time , the interval time between each task is an absolute 1000ms. Every time the scheduled time of the task is reached, the next task will be executed.
测试6：TimerTask.scheduleAtFixedRate(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, delay, period);Test Results
任务执行时间1：1547911834883
任务开始时间2：1547911834898
任务完成时间3：1547911834964
任务执行时间1：1547911835883
任务开始时间2：1547911835897
任务完成时间3：1547911835928
任务执行时间1：1547911836883
任务开始时间2：1547911836890
任务完成时间3：1547911836908Analysis of test results:
From the test results, we can see that when the task execution time is shorter than the task interval time , the interval time between each task is an absolute 1000ms. Every time the scheduled time of the task is reached, the next task will be executed.
Next, change times to 20000000, and test the running time of testRun() when times = 20000000, the test result is
任务开始时间2：1547908475998
任务完成时间3：1547908478588
任务开始时间2：1547908568611
任务完成时间3：1547908571142
任务开始时间2：1547908598520
任务完成时间3：1547908601113After multiple tests, the running time of testRun() is about 2500ms each time.
Test 7 and Test 10 mainly test the situation that the task duration is longer than the task interval time
测试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)Test Results
任务执行时间1：1547912035015
任务开始时间2：1547912035015
任务完成时间3：1547912037308
任务执行时间1：1547912037308
任务开始时间2：1547912037308
任务完成时间3：1547912039287
任务执行时间1：1547912039287
任务开始时间2：1547912039287
任务完成时间3：1547912041319Analysis of test results:
It can be seen from the test results that when the task execution time is longer than the task interval time , the time spent in judging whether to execute the next task is ignored after the execution of the last task is completed, and it can be considered that the next task will be executed immediately after the execution of the last task.
测试8：TimerTask.schedule(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.schedule(task, delay, period);Test Results
任务执行时间1：1547912515452
任务开始时间2：1547912515452
任务完成时间3：1547912517670
任务执行时间1：1547912517670
任务开始时间2：1547912517670
任务完成时间3：1547912519671
任务执行时间1：1547912519671
任务开始时间2：1547912519671
任务完成时间3：1547912521665
任务执行时间1：1547912521665
任务开始时间2：1547912521665
任务完成时间3：1547912523656It can be seen from the test results that when the task execution time is longer than the task interval time , the time spent in judging whether to execute the next task is ignored after the execution of the last task is completed, and it can be considered that the next task will be executed immediately after the execution of the last task.
Test9： 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);Test Results
任务开始时间2：1547912675002
任务执行时间1：1547912675000
任务完成时间3：1547912677359
任务执行时间1：1547912676000
任务开始时间2：1547912677359
任务完成时间3：1547912679409
任务执行时间1：1547912677000
任务开始时间2：1547912679409
任务完成时间3：1547912681662
任务执行时间1：1547912678000
任务开始时间2：1547912681663
任务完成时间3：1547912683893Analysis of test results:
It can be seen from the test results that when the task execution time is longer than the task interval time , the difference between each task execution time interval is 1000ms, and the execution time of the next task is not affected by the execution end time of the previous task. So it is called fixed frequency execution task .
测试10：TimerTask.scheduleAtFixedRate(TimerTask task, long delay, long period)
long delay = 1000; // 任务延迟毫秒数
long period = 1000; // 任务间隔毫秒数
timer.scheduleAtFixedRate(task, delay, period);Test Results
任务执行时间1：1547913408826
任务开始时间2：1547913408829
任务完成时间3：1547913411057
任务执行时间1：1547913409826
任务开始时间2：1547913411057
任务完成时间3：1547913413039
任务执行时间1：1547913410826
任务开始时间2：1547913413039
任务完成时间3：1547913415014
任务执行时间1：1547913411826
任务开始时间2：1547913415014
任务完成时间3：1547913416982Analysis of test results:
It can be seen from the test results that when the task execution time is longer than the task interval time , the difference between each task execution time interval is 1000ms, and the execution time of the next task is not affected by the execution end time of the previous task. So it is called fixed frequency execution task .
6. Summary of test results
From the results of tests 2, 4, 7, and 8, we can see that the Timer.schedule() construction method, when the task execution time is shorter than the task interval time , after the last task is executed, the execution time of the next task is the same as the last task The execution time interval (ignoring the time to judge whether to execute and other times) is basically period. When the task execution time is greater than the task interval time , the next task will be executed immediately after the last task execution ends (ignoring the time to judge whether to execute and other times).
From the results of tests 5, 6, 9, and 10, we can see that with the Timer.scheduleAtFixedRate() construction method, the execution time intervals of the previous and subsequent tasks are absolute periods, and the execution time of the task does not affect the normal execution of the next task.
Summarize:
We can think of a schedule as a child’s shoe without a plan. Take one step at a time. If today’s task in the schedule is completed ahead of schedule, we will continue to complete tomorrow’s task tomorrow. If today’s task in the schedule is delayed due to something, tomorrow’s schedule will finish yesterday first. The rest of the tasks and then complete the task of the day. So the schedule focuses on whether the current task has been completed, and only executes one task at a time.
And we can imagine scheduleAtFixedRate as a planned children's shoes, scheduleAtFixedRate starts to execute the task of the day at a fixed point every day, if yesterday's task has not been completed, then scheduleAtFixedRate will execute yesterday's and today's tasks at the same time. So scheduleAtFixedRate focuses on whether the task starts regularly, regardless of whether the task has been completed. If the task is not completed, then the two tasks will be performed at the same time.
important point
When using scheduleAtFixedRate we need to consider thread safety issues, because the same transaction may be executed concurrently.
This article is purely personal handwriting and is written based on personal understanding. If there are any mistakes, please leave a message in the comment area to correct me.
7. Complete Timer source code:
/*
* 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);
}
}