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 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 */ 90 public 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