diff options
| author | Jesse Wilson <jessewilson@google.com> | 2010-05-04 15:41:36 -0700 |
|---|---|---|
| committer | Android (Google) Code Review <android-gerrit@google.com> | 2010-05-04 15:41:36 -0700 |
| commit | 0a98ab45e3566542f2d669eb0ffd28a560d97d28 (patch) | |
| tree | 6f6e63f36c2fc650becff94974bfb649dffa3706 /luni | |
| parent | 0ebe2220e2828228b3d9b1003fbc5a47d80872e7 (diff) | |
| parent | c38102eb6f7a01fe70094a63054337f53ab5283d (diff) | |
| download | libcore-0a98ab45e3566542f2d669eb0ffd28a560d97d28.zip libcore-0a98ab45e3566542f2d669eb0ffd28a560d97d28.tar.gz libcore-0a98ab45e3566542f2d669eb0ffd28a560d97d28.tar.bz2 | |
Merge "Improving the doc for java.util.Timer" into dalvik-dev
Diffstat (limited to 'luni')
| -rw-r--r-- | luni/src/main/java/java/util/Timer.java | 61 |
1 files changed, 29 insertions, 32 deletions
diff --git a/luni/src/main/java/java/util/Timer.java b/luni/src/main/java/java/util/Timer.java index 3d34974..e30a745 100644 --- a/luni/src/main/java/java/util/Timer.java +++ b/luni/src/main/java/java/util/Timer.java @@ -20,39 +20,36 @@ package java.util; import org.apache.harmony.luni.util.Msg; /** - * {@code Timer}s are used to schedule jobs for execution in a background process. A - * single thread is used for the scheduling and this thread has the option of - * being a daemon thread. By calling {@code cancel} you can terminate a - * {@code Timer} and its associated thread. All tasks which are scheduled to run after - * this point are cancelled. Tasks are executed sequentially but are subject to - * the delays from other tasks run methods. If a specific task takes an - * excessive amount of time to run it may impact the time at which subsequent - * tasks may run. - * <p> + * Timers schedule one-shot or recurring {@link TimerTask tasks} for execution. + * Prefer {@link java.util.concurrent.ScheduledThreadPoolExecutor + * ScheduledThreadPoolExecutor} for new code. * - * The {@code TimerTask} does not offer any guarantees about the real-time nature of - * scheduling tasks as its underlying implementation relies on the - * {@code Object.wait(long)} method. - * <p> - * Multiple threads can share a single {@code Timer} without the need for their own - * synchronization. - * <p> - * A {@code Timer} can be set to schedule tasks either at a fixed rate or - * with a fixed period. Fixed-period execution is the default. - * <p> - * The difference between fixed-rate and fixed-period execution - * is the following: With fixed-rate execution, the start time of each - * successive run of the task is scheduled in absolute terms without regard for when the previous - * task run actually took place. This can result in a series of bunched-up runs - * (one launched immediately after another) if busy resources or other - * system delays prevent the {@code Timer} from firing for an extended time. - * With fixed-period execution, each successive run of the - * task is scheduled relative to the start time of the previous run of the - * task, so two runs of the task are never fired closer together in time than - * the specified {@code period}. + * <p>Each timer has one thread on which tasks are executed sequentially. When + * this thread is busy running a task, runnable tasks may be subject to delays. + * + * <p>One-shot are scheduled to run at an absolute time or after a relative + * delay. + * + * <p>Recurring tasks are scheduled with either a fixed period or a fixed rate: + * <ul> + * <li>With the default <strong>fixed-period execution</strong>, each + * successive run of a task is scheduled relative to the start time of + * the previous run, so two runs are never fired closer together in time + * than the specified {@code period}. + * <li>With <strong>fixed-rate execution</strong>, the start time of each + * successive run of a task is scheduled without regard for when the + * previous run took place. This may result in a series of bunched-up runs + * (one launched immediately after another) if delays prevent the timer + * from starting tasks on time. + * </ul> * - * @see TimerTask - * @see java.lang.Object#wait(long) + * <p>When a timer is no longer needed, users should call {@link #cancel}, which + * releases the timer's thread and other resources. Timers not explicitly + * cancelled may hold resources indefinitely. + * + * <p>This class does not offer guarantees about the real-time nature of task + * scheduling. Multiple threads can share a single timer without + * synchronization. */ public class Timer { @@ -399,7 +396,7 @@ public class Timer { } /** - * Cancels the {@code Timer} and removes any scheduled tasks. If there is a + * Cancels the {@code Timer} and all scheduled tasks. If there is a * currently running task it is not affected. No more tasks may be scheduled * on this {@code Timer}. Subsequent calls do nothing. */ |