1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.os;
18
19
20/**
21 * Core timekeeping facilities.
22 *
23 * <p> Three different clocks are available, and they should not be confused:
24 *
25 * <ul>
26 *     <li> <p> {@link System#currentTimeMillis System.currentTimeMillis()}
27 *     is the standard "wall" clock (time and date) expressing milliseconds
28 *     since the epoch.  The wall clock can be set by the user or the phone
29 *     network (see {@link #setCurrentTimeMillis}), so the time may jump
30 *     backwards or forwards unpredictably.  This clock should only be used
31 *     when correspondence with real-world dates and times is important, such
32 *     as in a calendar or alarm clock application.  Interval or elapsed
33 *     time measurements should use a different clock.  If you are using
34 *     System.currentTimeMillis(), consider listening to the
35 *     {@link android.content.Intent#ACTION_TIME_TICK ACTION_TIME_TICK},
36 *     {@link android.content.Intent#ACTION_TIME_CHANGED ACTION_TIME_CHANGED}
37 *     and {@link android.content.Intent#ACTION_TIMEZONE_CHANGED
38 *     ACTION_TIMEZONE_CHANGED} {@link android.content.Intent Intent}
39 *     broadcasts to find out when the time changes.
40 *
41 *     <li> <p> {@link #uptimeMillis} is counted in milliseconds since the
42 *     system was booted.  This clock stops when the system enters deep
43 *     sleep (CPU off, display dark, device waiting for external input),
44 *     but is not affected by clock scaling, idle, or other power saving
45 *     mechanisms.  This is the basis for most interval timing
46 *     such as {@link Thread#sleep(long) Thread.sleep(millls)},
47 *     {@link Object#wait(long) Object.wait(millis)}, and
48 *     {@link System#nanoTime System.nanoTime()}.  This clock is guaranteed
49 *     to be monotonic, and is the recommended basis for the general purpose
50 *     interval timing of user interface events, performance measurements,
51 *     and anything else that does not need to measure elapsed time during
52 *     device sleep.  Most methods that accept a timestamp value expect the
53 *     {@link #uptimeMillis} clock.
54 *
55 *     <li> <p> {@link #elapsedRealtime} is counted in milliseconds since the
56 *     system was booted, including deep sleep.  This clock should be used
57 *     when measuring time intervals that may span periods of system sleep.
58 * </ul>
59 *
60 * There are several mechanisms for controlling the timing of events:
61 *
62 * <ul>
63 *     <li> <p> Standard functions like {@link Thread#sleep(long)
64 *     Thread.sleep(millis)} and {@link Object#wait(long) Object.wait(millis)}
65 *     are always available.  These functions use the {@link #uptimeMillis}
66 *     clock; if the device enters sleep, the remainder of the time will be
67 *     postponed until the device wakes up.  These synchronous functions may
68 *     be interrupted with {@link Thread#interrupt Thread.interrupt()}, and
69 *     you must handle {@link InterruptedException}.
70 *
71 *     <li> <p> {@link #sleep SystemClock.sleep(millis)} is a utility function
72 *     very similar to {@link Thread#sleep(long) Thread.sleep(millis)}, but it
73 *     ignores {@link InterruptedException}.  Use this function for delays if
74 *     you do not use {@link Thread#interrupt Thread.interrupt()}, as it will
75 *     preserve the interrupted state of the thread.
76 *
77 *     <li> <p> The {@link android.os.Handler} class can schedule asynchronous
78 *     callbacks at an absolute or relative time.  Handler objects also use the
79 *     {@link #uptimeMillis} clock, and require an {@link android.os.Looper
80 *     event loop} (normally present in any GUI application).
81 *
82 *     <li> <p> The {@link android.app.AlarmManager} can trigger one-time or
83 *     recurring events which occur even when the device is in deep sleep
84 *     or your application is not running.  Events may be scheduled with your
85 *     choice of {@link java.lang.System#currentTimeMillis} (RTC) or
86 *     {@link #elapsedRealtime} (ELAPSED_REALTIME), and cause an
87 *     {@link android.content.Intent} broadcast when they occur.
88 * </ul>
89 */
90public final class SystemClock {
91    /**
92     * This class is uninstantiable.
93     */
94    private SystemClock() {
95        // This space intentionally left blank.
96    }
97
98    /**
99     * Waits a given number of milliseconds (of uptimeMillis) before returning.
100     * Similar to {@link java.lang.Thread#sleep(long)}, but does not throw
101     * {@link InterruptedException}; {@link Thread#interrupt()} events are
102     * deferred until the next interruptible operation.  Does not return until
103     * at least the specified number of milliseconds has elapsed.
104     *
105     * @param ms to sleep before returning, in milliseconds of uptime.
106     */
107    public static void sleep(long ms)
108    {
109        long start = uptimeMillis();
110        long duration = ms;
111        boolean interrupted = false;
112        do {
113            try {
114                Thread.sleep(duration);
115            }
116            catch (InterruptedException e) {
117                interrupted = true;
118            }
119            duration = start + ms - uptimeMillis();
120        } while (duration > 0);
121
122        if (interrupted) {
123            // Important: we don't want to quietly eat an interrupt() event,
124            // so we make sure to re-interrupt the thread so that the next
125            // call to Thread.sleep() or Object.wait() will be interrupted.
126            Thread.currentThread().interrupt();
127        }
128    }
129
130    /**
131     * Sets the current wall time, in milliseconds.  Requires the calling
132     * process to have appropriate permissions.
133     *
134     * @return if the clock was successfully set to the specified time.
135     */
136    native public static boolean setCurrentTimeMillis(long millis);
137
138    /**
139     * Returns milliseconds since boot, not counting time spent in deep sleep.
140     * <b>Note:</b> This value may get reset occasionally (before it would
141     * otherwise wrap around).
142     *
143     * @return milliseconds of non-sleep uptime since boot.
144     */
145    native public static long uptimeMillis();
146
147    /**
148     * Returns milliseconds since boot, including time spent in sleep.
149     *
150     * @return elapsed milliseconds since boot.
151     */
152    native public static long elapsedRealtime();
153
154    /**
155     * Returns milliseconds running in the current thread.
156     *
157     * @return elapsed milliseconds in the thread
158     */
159    public static native long currentThreadTimeMillis();
160
161    /**
162     * Returns microseconds running in the current thread.
163     *
164     * @return elapsed microseconds in the thread
165     *
166     * @hide
167     */
168    public static native long currentThreadTimeMicro();
169
170    /**
171     * Returns current wall time in  microseconds.
172     *
173     * @return elapsed microseconds in wall time
174     *
175     * @hide
176     */
177    public static native long currentTimeMicro();
178}
179