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 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.util.Log; 22 import android.util.Printer; 23 24 /** 25 * Class used to run a message loop for a thread. Threads by default do 26 * not have a message loop associated with them; to create one, call 27 * {@link #prepare} in the thread that is to run the loop, and then 28 * {@link #loop} to have it process messages until the loop is stopped. 29 * 30 * <p>Most interaction with a message loop is through the 31 * {@link Handler} class. 32 * 33 * <p>This is a typical example of the implementation of a Looper thread, 34 * using the separation of {@link #prepare} and {@link #loop} to create an 35 * initial Handler to communicate with the Looper. 36 * 37 * <pre> 38 * class LooperThread extends Thread { 39 * public Handler mHandler; 40 * 41 * public void run() { 42 * Looper.prepare(); 43 * 44 * mHandler = new Handler() { 45 * public void handleMessage(Message msg) { 46 * // process incoming messages here 47 * } 48 * }; 49 * 50 * Looper.loop(); 51 * } 52 * }</pre> 53 */ 54 public final class Looper { 55 /* 56 * API Implementation Note: 57 * 58 * This class contains the code required to set up and manage an event loop 59 * based on MessageQueue. APIs that affect the state of the queue should be 60 * defined on MessageQueue or Handler rather than on Looper itself. For example, 61 * idle handlers and sync barriers are defined on the queue whereas preparing the 62 * thread, looping, and quitting are defined on the looper. 63 */ 64 65 private static final String TAG = "Looper"; 66 67 // sThreadLocal.get() will return null unless you've called prepare(). 68 static final ThreadLocal<Looper> sThreadLocal = new ThreadLocal<Looper>(); 69 private static Looper sMainLooper; // guarded by Looper.class 70 71 final MessageQueue mQueue; 72 final Thread mThread; 73 74 private Printer mLogging; 75 private long mTraceTag; 76 77 /** Initialize the current thread as a looper. 78 * This gives you a chance to create handlers that then reference 79 * this looper, before actually starting the loop. Be sure to call 80 * {@link #loop()} after calling this method, and end it by calling 81 * {@link #quit()}. 82 */ 83 public static void prepare() { 84 prepare(true); 85 } 86 87 private static void prepare(boolean quitAllowed) { 88 if (sThreadLocal.get() != null) { 89 throw new RuntimeException("Only one Looper may be created per thread"); 90 } 91 sThreadLocal.set(new Looper(quitAllowed)); 92 } 93 94 /** 95 * Initialize the current thread as a looper, marking it as an 96 * application's main looper. The main looper for your application 97 * is created by the Android environment, so you should never need 98 * to call this function yourself. See also: {@link #prepare()} 99 */ 100 public static void prepareMainLooper() { 101 prepare(false); 102 synchronized (Looper.class) { 103 if (sMainLooper != null) { 104 throw new IllegalStateException("The main Looper has already been prepared."); 105 } 106 sMainLooper = myLooper(); 107 } 108 } 109 110 /** 111 * Returns the application's main looper, which lives in the main thread of the application. 112 */ 113 public static Looper getMainLooper() { 114 synchronized (Looper.class) { 115 return sMainLooper; 116 } 117 } 118 119 /** 120 * Run the message queue in this thread. Be sure to call 121 * {@link #quit()} to end the loop. 122 */ 123 public static void loop() { 124 final Looper me = myLooper(); 125 if (me == null) { 126 throw new RuntimeException("No Looper; Looper.prepare() wasn't called on this thread."); 127 } 128 final MessageQueue queue = me.mQueue; 129 130 // Make sure the identity of this thread is that of the local process, 131 // and keep track of what that identity token actually is. 132 Binder.clearCallingIdentity(); 133 final long ident = Binder.clearCallingIdentity(); 134 135 for (;;) { 136 Message msg = queue.next(); // might block 137 if (msg == null) { 138 // No message indicates that the message queue is quitting. 139 return; 140 } 141 142 // This must be in a local variable, in case a UI event sets the logger 143 final Printer logging = me.mLogging; 144 if (logging != null) { 145 logging.println(">>>>> Dispatching to " + msg.target + " " + 146 msg.callback + ": " + msg.what); 147 } 148 149 final long traceTag = me.mTraceTag; 150 if (traceTag != 0) { 151 Trace.traceBegin(traceTag, msg.target.getTraceName(msg)); 152 } 153 try { 154 msg.target.dispatchMessage(msg); 155 } finally { 156 if (traceTag != 0) { 157 Trace.traceEnd(traceTag); 158 } 159 } 160 161 if (logging != null) { 162 logging.println("<<<<< Finished to " + msg.target + " " + msg.callback); 163 } 164 165 // Make sure that during the course of dispatching the 166 // identity of the thread wasn't corrupted. 167 final long newIdent = Binder.clearCallingIdentity(); 168 if (ident != newIdent) { 169 Log.wtf(TAG, "Thread identity changed from 0x" 170 + Long.toHexString(ident) + " to 0x" 171 + Long.toHexString(newIdent) + " while dispatching to " 172 + msg.target.getClass().getName() + " " 173 + msg.callback + " what=" + msg.what); 174 } 175 176 msg.recycleUnchecked(); 177 } 178 } 179 180 /** 181 * Return the Looper object associated with the current thread. Returns 182 * null if the calling thread is not associated with a Looper. 183 */ 184 public static @Nullable Looper myLooper() { 185 return sThreadLocal.get(); 186 } 187 188 /** 189 * Return the {@link MessageQueue} object associated with the current 190 * thread. This must be called from a thread running a Looper, or a 191 * NullPointerException will be thrown. 192 */ 193 public static @NonNull MessageQueue myQueue() { 194 return myLooper().mQueue; 195 } 196 197 private Looper(boolean quitAllowed) { 198 mQueue = new MessageQueue(quitAllowed); 199 mThread = Thread.currentThread(); 200 } 201 202 /** 203 * Returns true if the current thread is this looper's thread. 204 */ 205 public boolean isCurrentThread() { 206 return Thread.currentThread() == mThread; 207 } 208 209 /** 210 * Control logging of messages as they are processed by this Looper. If 211 * enabled, a log message will be written to <var>printer</var> 212 * at the beginning and ending of each message dispatch, identifying the 213 * target Handler and message contents. 214 * 215 * @param printer A Printer object that will receive log messages, or 216 * null to disable message logging. 217 */ 218 public void setMessageLogging(@Nullable Printer printer) { 219 mLogging = printer; 220 } 221 222 /** {@hide} */ 223 public void setTraceTag(long traceTag) { 224 mTraceTag = traceTag; 225 } 226 227 /** 228 * Quits the looper. 229 * <p> 230 * Causes the {@link #loop} method to terminate without processing any 231 * more messages in the message queue. 232 * </p><p> 233 * Any attempt to post messages to the queue after the looper is asked to quit will fail. 234 * For example, the {@link Handler#sendMessage(Message)} method will return false. 235 * </p><p class="note"> 236 * Using this method may be unsafe because some messages may not be delivered 237 * before the looper terminates. Consider using {@link #quitSafely} instead to ensure 238 * that all pending work is completed in an orderly manner. 239 * </p> 240 * 241 * @see #quitSafely 242 */ 243 public void quit() { 244 mQueue.quit(false); 245 } 246 247 /** 248 * Quits the looper safely. 249 * <p> 250 * Causes the {@link #loop} method to terminate as soon as all remaining messages 251 * in the message queue that are already due to be delivered have been handled. 252 * However pending delayed messages with due times in the future will not be 253 * delivered before the loop terminates. 254 * </p><p> 255 * Any attempt to post messages to the queue after the looper is asked to quit will fail. 256 * For example, the {@link Handler#sendMessage(Message)} method will return false. 257 * </p> 258 */ 259 public void quitSafely() { 260 mQueue.quit(true); 261 } 262 263 /** 264 * Gets the Thread associated with this Looper. 265 * 266 * @return The looper's thread. 267 */ 268 public @NonNull Thread getThread() { 269 return mThread; 270 } 271 272 /** 273 * Gets this looper's message queue. 274 * 275 * @return The looper's message queue. 276 */ 277 public @NonNull MessageQueue getQueue() { 278 return mQueue; 279 } 280 281 /** 282 * Dumps the state of the looper for debugging purposes. 283 * 284 * @param pw A printer to receive the contents of the dump. 285 * @param prefix A prefix to prepend to each line which is printed. 286 */ 287 public void dump(@NonNull Printer pw, @NonNull String prefix) { 288 pw.println(prefix + toString()); 289 mQueue.dump(pw, prefix + " "); 290 } 291 292 @Override 293 public String toString() { 294 return "Looper (" + mThread.getName() + ", tid " + mThread.getId() 295 + ") {" + Integer.toHexString(System.identityHashCode(this)) + "}"; 296 } 297 } 298
