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 17 package 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 suitable for interval timing when the 50 * interval does not span device sleep. Most methods that accept a 51 * timestamp value currently expect the {@link #uptimeMillis} clock. 52 * 53 * <li> <p> {@link #elapsedRealtime} and {@link #elapsedRealtimeNanos} 54 * return the time since the system was booted, and include deep sleep. 55 * This clock is guaranteed to be monotonic, and continues to tick even 56 * when the CPU is in power saving modes, so is the recommend basis 57 * for general purpose interval timing. 58 * 59 * </ul> 60 * 61 * There are several mechanisms for controlling the timing of events: 62 * 63 * <ul> 64 * <li> <p> Standard functions like {@link Thread#sleep(long) 65 * Thread.sleep(millis)} and {@link Object#wait(long) Object.wait(millis)} 66 * are always available. These functions use the {@link #uptimeMillis} 67 * clock; if the device enters sleep, the remainder of the time will be 68 * postponed until the device wakes up. These synchronous functions may 69 * be interrupted with {@link Thread#interrupt Thread.interrupt()}, and 70 * you must handle {@link InterruptedException}. 71 * 72 * <li> <p> {@link #sleep SystemClock.sleep(millis)} is a utility function 73 * very similar to {@link Thread#sleep(long) Thread.sleep(millis)}, but it 74 * ignores {@link InterruptedException}. Use this function for delays if 75 * you do not use {@link Thread#interrupt Thread.interrupt()}, as it will 76 * preserve the interrupted state of the thread. 77 * 78 * <li> <p> The {@link android.os.Handler} class can schedule asynchronous 79 * callbacks at an absolute or relative time. Handler objects also use the 80 * {@link #uptimeMillis} clock, and require an {@link android.os.Looper 81 * event loop} (normally present in any GUI application). 82 * 83 * <li> <p> The {@link android.app.AlarmManager} can trigger one-time or 84 * recurring events which occur even when the device is in deep sleep 85 * or your application is not running. Events may be scheduled with your 86 * choice of {@link java.lang.System#currentTimeMillis} (RTC) or 87 * {@link #elapsedRealtime} (ELAPSED_REALTIME), and cause an 88 * {@link android.content.Intent} broadcast when they occur. 89 * </ul> 90 */ 91 public final class SystemClock { 92 /** 93 * This class is uninstantiable. 94 */ 95 private SystemClock() { 96 // This space intentionally left blank. 97 } 98 99 /** 100 * Waits a given number of milliseconds (of uptimeMillis) before returning. 101 * Similar to {@link java.lang.Thread#sleep(long)}, but does not throw 102 * {@link InterruptedException}; {@link Thread#interrupt()} events are 103 * deferred until the next interruptible operation. Does not return until 104 * at least the specified number of milliseconds has elapsed. 105 * 106 * @param ms to sleep before returning, in milliseconds of uptime. 107 */ 108 public static void sleep(long ms) 109 { 110 long start = uptimeMillis(); 111 long duration = ms; 112 boolean interrupted = false; 113 do { 114 try { 115 Thread.sleep(duration); 116 } 117 catch (InterruptedException e) { 118 interrupted = true; 119 } 120 duration = start + ms - uptimeMillis(); 121 } while (duration > 0); 122 123 if (interrupted) { 124 // Important: we don't want to quietly eat an interrupt() event, 125 // so we make sure to re-interrupt the thread so that the next 126 // call to Thread.sleep() or Object.wait() will be interrupted. 127 Thread.currentThread().interrupt(); 128 } 129 } 130 131 /** 132 * Sets the current wall time, in milliseconds. Requires the calling 133 * process to have appropriate permissions. 134 * 135 * @return if the clock was successfully set to the specified time. 136 */ 137 native public static boolean setCurrentTimeMillis(long millis); 138 139 /** 140 * Returns milliseconds since boot, not counting time spent in deep sleep. 141 * 142 * @return milliseconds of non-sleep uptime since boot. 143 */ 144 native public static long uptimeMillis(); 145 146 /** 147 * Returns milliseconds since boot, including time spent in sleep. 148 * 149 * @return elapsed milliseconds since boot. 150 */ 151 native public static long elapsedRealtime(); 152 153 /** 154 * Returns nanoseconds since boot, including time spent in sleep. 155 * 156 * @return elapsed nanoseconds since boot. 157 */ 158 public static native long elapsedRealtimeNanos(); 159 160 /** 161 * Returns milliseconds running in the current thread. 162 * 163 * @return elapsed milliseconds in the thread 164 */ 165 public static native long currentThreadTimeMillis(); 166 167 /** 168 * Returns microseconds running in the current thread. 169 * 170 * @return elapsed microseconds in the thread 171 * 172 * @hide 173 */ 174 public static native long currentThreadTimeMicro(); 175 176 /** 177 * Returns current wall time in microseconds. 178 * 179 * @return elapsed microseconds in wall time 180 * 181 * @hide 182 */ 183 public static native long currentTimeMicro(); 184 } 185
