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
19import android.app.IAlarmManager;
20import android.content.Context;
21import android.util.Slog;
22
23/**
24 * Core timekeeping facilities.
25 *
26 * <p> Three different clocks are available, and they should not be confused:
27 *
28 * <ul>
29 *     <li> <p> {@link System#currentTimeMillis System.currentTimeMillis()}
30 *     is the standard "wall" clock (time and date) expressing milliseconds
31 *     since the epoch.  The wall clock can be set by the user or the phone
32 *     network (see {@link #setCurrentTimeMillis}), so the time may jump
33 *     backwards or forwards unpredictably.  This clock should only be used
34 *     when correspondence with real-world dates and times is important, such
35 *     as in a calendar or alarm clock application.  Interval or elapsed
36 *     time measurements should use a different clock.  If you are using
37 *     System.currentTimeMillis(), consider listening to the
38 *     {@link android.content.Intent#ACTION_TIME_TICK ACTION_TIME_TICK},
39 *     {@link android.content.Intent#ACTION_TIME_CHANGED ACTION_TIME_CHANGED}
40 *     and {@link android.content.Intent#ACTION_TIMEZONE_CHANGED
41 *     ACTION_TIMEZONE_CHANGED} {@link android.content.Intent Intent}
42 *     broadcasts to find out when the time changes.
43 *
44 *     <li> <p> {@link #uptimeMillis} is counted in milliseconds since the
45 *     system was booted.  This clock stops when the system enters deep
46 *     sleep (CPU off, display dark, device waiting for external input),
47 *     but is not affected by clock scaling, idle, or other power saving
48 *     mechanisms.  This is the basis for most interval timing
49 *     such as {@link Thread#sleep(long) Thread.sleep(millls)},
50 *     {@link Object#wait(long) Object.wait(millis)}, and
51 *     {@link System#nanoTime System.nanoTime()}.  This clock is guaranteed
52 *     to be monotonic, and is suitable for interval timing when the
53 *     interval does not span device sleep.  Most methods that accept a
54 *     timestamp value currently expect the {@link #uptimeMillis} clock.
55 *
56 *     <li> <p> {@link #elapsedRealtime} and {@link #elapsedRealtimeNanos}
57 *     return the time since the system was booted, and include deep sleep.
58 *     This clock is guaranteed to be monotonic, and continues to tick even
59 *     when the CPU is in power saving modes, so is the recommend basis
60 *     for general purpose interval timing.
61 *
62 * </ul>
63 *
64 * There are several mechanisms for controlling the timing of events:
65 *
66 * <ul>
67 *     <li> <p> Standard functions like {@link Thread#sleep(long)
68 *     Thread.sleep(millis)} and {@link Object#wait(long) Object.wait(millis)}
69 *     are always available.  These functions use the {@link #uptimeMillis}
70 *     clock; if the device enters sleep, the remainder of the time will be
71 *     postponed until the device wakes up.  These synchronous functions may
72 *     be interrupted with {@link Thread#interrupt Thread.interrupt()}, and
73 *     you must handle {@link InterruptedException}.
74 *
75 *     <li> <p> {@link #sleep SystemClock.sleep(millis)} is a utility function
76 *     very similar to {@link Thread#sleep(long) Thread.sleep(millis)}, but it
77 *     ignores {@link InterruptedException}.  Use this function for delays if
78 *     you do not use {@link Thread#interrupt Thread.interrupt()}, as it will
79 *     preserve the interrupted state of the thread.
80 *
81 *     <li> <p> The {@link android.os.Handler} class can schedule asynchronous
82 *     callbacks at an absolute or relative time.  Handler objects also use the
83 *     {@link #uptimeMillis} clock, and require an {@link android.os.Looper
84 *     event loop} (normally present in any GUI application).
85 *
86 *     <li> <p> The {@link android.app.AlarmManager} can trigger one-time or
87 *     recurring events which occur even when the device is in deep sleep
88 *     or your application is not running.  Events may be scheduled with your
89 *     choice of {@link java.lang.System#currentTimeMillis} (RTC) or
90 *     {@link #elapsedRealtime} (ELAPSED_REALTIME), and cause an
91 *     {@link android.content.Intent} broadcast when they occur.
92 * </ul>
93 */
94public final class SystemClock {
95    private static final String TAG = "SystemClock";
96
97    /**
98     * This class is uninstantiable.
99     */
100    private SystemClock() {
101        // This space intentionally left blank.
102    }
103
104    /**
105     * Waits a given number of milliseconds (of uptimeMillis) before returning.
106     * Similar to {@link java.lang.Thread#sleep(long)}, but does not throw
107     * {@link InterruptedException}; {@link Thread#interrupt()} events are
108     * deferred until the next interruptible operation.  Does not return until
109     * at least the specified number of milliseconds has elapsed.
110     *
111     * @param ms to sleep before returning, in milliseconds of uptime.
112     */
113    public static void sleep(long ms)
114    {
115        long start = uptimeMillis();
116        long duration = ms;
117        boolean interrupted = false;
118        do {
119            try {
120                Thread.sleep(duration);
121            }
122            catch (InterruptedException e) {
123                interrupted = true;
124            }
125            duration = start + ms - uptimeMillis();
126        } while (duration > 0);
127
128        if (interrupted) {
129            // Important: we don't want to quietly eat an interrupt() event,
130            // so we make sure to re-interrupt the thread so that the next
131            // call to Thread.sleep() or Object.wait() will be interrupted.
132            Thread.currentThread().interrupt();
133        }
134    }
135
136    /**
137     * Sets the current wall time, in milliseconds.  Requires the calling
138     * process to have appropriate permissions.
139     *
140     * @return if the clock was successfully set to the specified time.
141     */
142    public static boolean setCurrentTimeMillis(long millis) {
143        IBinder b = ServiceManager.getService(Context.ALARM_SERVICE);
144        IAlarmManager mgr = IAlarmManager.Stub.asInterface(b);
145        if (mgr == null) {
146            return false;
147        }
148
149        try {
150            return mgr.setTime(millis);
151        } catch (RemoteException e) {
152            Slog.e(TAG, "Unable to set RTC", e);
153        } catch (SecurityException e) {
154            Slog.e(TAG, "Unable to set RTC", e);
155        }
156
157        return false;
158    }
159
160    /**
161     * Returns milliseconds since boot, not counting time spent in deep sleep.
162     *
163     * @return milliseconds of non-sleep uptime since boot.
164     */
165    native public static long uptimeMillis();
166
167    /**
168     * Returns milliseconds since boot, including time spent in sleep.
169     *
170     * @return elapsed milliseconds since boot.
171     */
172    native public static long elapsedRealtime();
173
174    /**
175     * Returns nanoseconds since boot, including time spent in sleep.
176     *
177     * @return elapsed nanoseconds since boot.
178     */
179    public static native long elapsedRealtimeNanos();
180
181    /**
182     * Returns milliseconds running in the current thread.
183     *
184     * @return elapsed milliseconds in the thread
185     */
186    public static native long currentThreadTimeMillis();
187
188    /**
189     * Returns microseconds running in the current thread.
190     *
191     * @return elapsed microseconds in the thread
192     *
193     * @hide
194     */
195    public static native long currentThreadTimeMicro();
196
197    /**
198     * Returns current wall time in  microseconds.
199     *
200     * @return elapsed microseconds in wall time
201     *
202     * @hide
203     */
204    public static native long currentTimeMicro();
205}
206