java/util/TimerTask.java

/*
 * @(#)TimerTask.java   1.9 03/12/19
 *
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.util;

/**
 * A task that can be scheduled for one-time or repeated execution by a Timer.
 *
 * @author  Josh Bloch
 * @version 1.9, 12/19/03
 * @see     Timer
 * @since   1.3
 */

public abstract class TimerTask implements Runnable {
    /**
     * This object is used to control access to the TimerTask internals.
     */
    final Object lock = new Object();

    /**
     * The state of this task, chosen from the constants below.
     */
    int state = VIRGIN;

    /**
     * This task has not yet been scheduled.
     */
    static final int VIRGIN = 0;

    /**
     * This task is scheduled for execution.  If it is a non-repeating task,
     * it has not yet been executed.
     */
    static final int SCHEDULED   = 1;

    /**
     * This non-repeating task has already executed (or is currently
     * executing) and has not been cancelled.
     */
    static final int EXECUTED    = 2;

    /**
     * This task has been cancelled (with a call to TimerTask.cancel).
     */
    static final int CANCELLED   = 3;

    /**
     * Next execution time for this task in the format set by Timer
     * schedule methods (nanoseconds since the Timer class was initialized),
     * assuming this task is scheduled for execution.  For repeating
     * tasks, this field is updated prior to each task execution.
     */
    long nextExecutionTime;

    /**
     * Period in nanoseconds for repeating tasks.  A positive value indicates
     * fixed-rate execution.  A negative value indicates fixed-delay execution.
     * A value of 0 indicates a non-repeating task.
     */
    long period = 0;

    /**
     * Creates a new timer task.
     */
    protected TimerTask() {
    }

    /**
     * The action to be performed by this timer task.
     */
    public abstract void run();

    /**
     * Cancels this timer task.  If the task has been scheduled for one-time
     * execution and has not yet run, or has not yet been scheduled, it will
     * never run.  If the task has been scheduled for repeated execution, it
     * will never run again.  (If the task is running when this call occurs,
     * the task will run to completion, but will never run again.)
     *
     * <p>Note that calling this method from within the <tt>run</tt> method of
     * a repeating timer task absolutely guarantees that the timer task will
     * not run again.
     *
     * <p>This method may be called repeatedly; the second and subsequent 
     * calls have no effect.
     *
     * @return true if this task is scheduled for one-time execution and has
     *         not yet run, or this task is scheduled for repeated execution.
     *         Returns false if the task was scheduled for one-time execution
     *         and has already run, or if the task was never scheduled, or if
     *         the task was already cancelled.  (Loosely speaking, this method
     *         returns <tt>true</tt> if it prevents one or more scheduled
     *         executions from taking place.)
     */
    public boolean cancel() {
        synchronized(lock) {
            boolean result = (state == SCHEDULED);
            state = CANCELLED;
            return result;
        }
    }

    /**
     * Returns the <i>scheduled</i> execution time of the most recent
     * <i>actual</i> execution of this task.  (If this method is invoked
     * while task execution is in progress, the return value is the scheduled
     * execution time of the ongoing task execution.)
     *
     * <p>This method is typically invoked from within a task's run method, to
     * determine whether the current execution of the task is sufficiently
     * timely to warrant performing the scheduled activity:
     * <pre>
     *   public void run() {
     *       if (System.currentTimeMillis() - scheduledExecutionTime() >=
     *           MAX_TARDINESS)
     *               return;  // Too late; skip this execution.
     *       // Perform the task
     *   }
     * </pre>

     * This method is typically <i>not</i> used in conjunction with
     * <i>fixed-delay execution</i> repeating tasks, as their scheduled
     * execution times are allowed to drift over time, and so are not terribly
     * significant.
     *
     * @return the time at which the most recent execution of this task was
     *         scheduled to occur, in the format returned by Date.getTime().
     *         The return value is undefined if the task has yet to commence
     *         its first execution.
     * @see Date#getTime()
     */
    public long scheduledExecutionTime() {
        synchronized(lock) {
            return Timer.executionTimeToMillis
                (period < 0 ? 
                 nextExecutionTime + period :
                 nextExecutionTime - period);
        }
    }
}
Revision:	1.1
Committed:	Mon Jan 19 15:56:47 2004 UTC (20 years, 4 months ago) by dl
Branch:	MAIN
Log Message:	Tentative timer update
#	User	Rev	Content
1	dl	1.1	/*
2			* @(#)TimerTask.java 1.9 03/12/19
3			*
4			* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5			* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6			*/
7
8			package java.util;
9
10			/**
11			* A task that can be scheduled for one-time or repeated execution by a Timer.
12			*
13			* @author Josh Bloch
14			* @version 1.9, 12/19/03
15			* @see Timer
16			* @since 1.3
17			*/
18
19			public abstract class TimerTask implements Runnable {
20			/**
21			* This object is used to control access to the TimerTask internals.
22			*/
23			final Object lock = new Object();
24
25			/**
26			* The state of this task, chosen from the constants below.
27			*/
28			int state = VIRGIN;
29
30			/**
31			* This task has not yet been scheduled.
32			*/
33			static final int VIRGIN = 0;
34
35			/**
36			* This task is scheduled for execution. If it is a non-repeating task,
37			* it has not yet been executed.
38			*/
39			static final int SCHEDULED = 1;
40
41			/**
42			* This non-repeating task has already executed (or is currently
43			* executing) and has not been cancelled.
44			*/
45			static final int EXECUTED = 2;
46
47			/**
48			* This task has been cancelled (with a call to TimerTask.cancel).
49			*/
50			static final int CANCELLED = 3;
51
52			/**
53			* Next execution time for this task in the format set by Timer
54			* schedule methods (nanoseconds since the Timer class was initialized),
55			* assuming this task is scheduled for execution. For repeating
56			* tasks, this field is updated prior to each task execution.
57			*/
58			long nextExecutionTime;
59
60			/**
61			* Period in nanoseconds for repeating tasks. A positive value indicates
62			* fixed-rate execution. A negative value indicates fixed-delay execution.
63			* A value of 0 indicates a non-repeating task.
64			*/
65			long period = 0;
66
67			/**
68			* Creates a new timer task.
69			*/
70			protected TimerTask() {
71			}
72
73			/**
74			* The action to be performed by this timer task.
75			*/
76			public abstract void run();
77
78			/**
79			* Cancels this timer task. If the task has been scheduled for one-time
80			* execution and has not yet run, or has not yet been scheduled, it will
81			* never run. If the task has been scheduled for repeated execution, it
82			* will never run again. (If the task is running when this call occurs,
83			* the task will run to completion, but will never run again.)
84			*
85			* <p>Note that calling this method from within the <tt>run</tt> method of
86			* a repeating timer task absolutely guarantees that the timer task will
87			* not run again.
88			*
89			* <p>This method may be called repeatedly; the second and subsequent
90			* calls have no effect.
91			*
92			* @return true if this task is scheduled for one-time execution and has
93			* not yet run, or this task is scheduled for repeated execution.
94			* Returns false if the task was scheduled for one-time execution
95			* and has already run, or if the task was never scheduled, or if
96			* the task was already cancelled. (Loosely speaking, this method
97			* returns <tt>true</tt> if it prevents one or more scheduled
98			* executions from taking place.)
99			*/
100			public boolean cancel() {
101			synchronized(lock) {
102			boolean result = (state == SCHEDULED);
103			state = CANCELLED;
104			return result;
105			}
106			}
107
108			/**
109			* Returns the <i>scheduled</i> execution time of the most recent
110			* <i>actual</i> execution of this task. (If this method is invoked
111			* while task execution is in progress, the return value is the scheduled
112			* execution time of the ongoing task execution.)
113			*
114			* <p>This method is typically invoked from within a task's run method, to
115			* determine whether the current execution of the task is sufficiently
116			* timely to warrant performing the scheduled activity:
117			* <pre>
118			* public void run() {
119			* if (System.currentTimeMillis() - scheduledExecutionTime() >=
120			* MAX_TARDINESS)
121			* return; // Too late; skip this execution.
122			* // Perform the task
123			* }
124			* </pre>
125
126			* This method is typically <i>not</i> used in conjunction with
127			* <i>fixed-delay execution</i> repeating tasks, as their scheduled
128			* execution times are allowed to drift over time, and so are not terribly
129			* significant.
130			*
131			* @return the time at which the most recent execution of this task was
132			* scheduled to occur, in the format returned by Date.getTime().
133			* The return value is undefined if the task has yet to commence
134			* its first execution.
135			* @see Date#getTime()
136			*/
137			public long scheduledExecutionTime() {
138			synchronized(lock) {
139			return Timer.executionTimeToMillis
140			(period < 0 ?
141			nextExecutionTime + period :
142			nextExecutionTime - period);
143			}
144			}
145			}