Looper.java revision f9e989d5f09e72f5c9a59d713521f37d3fdd93dd
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.util.Log; 20import android.util.Printer; 21import android.util.PrefixPrinter; 22 23/** 24 * Class used to run a message loop for a thread. Threads by default do 25 * not have a message loop associated with them; to create one, call 26 * {@link #prepare} in the thread that is to run the loop, and then 27 * {@link #loop} to have it process messages until the loop is stopped. 28 * 29 * <p>Most interaction with a message loop is through the 30 * {@link Handler} class. 31 * 32 * <p>This is a typical example of the implementation of a Looper thread, 33 * using the separation of {@link #prepare} and {@link #loop} to create an 34 * initial Handler to communicate with the Looper. 35 * 36 * <pre> 37 * class LooperThread extends Thread { 38 * public Handler mHandler; 39 * 40 * public void run() { 41 * Looper.prepare(); 42 * 43 * mHandler = new Handler() { 44 * public void handleMessage(Message msg) { 45 * // process incoming messages here 46 * } 47 * }; 48 * 49 * Looper.loop(); 50 * } 51 * }</pre> 52 */ 53public final class Looper { 54 private static final String TAG = "Looper"; 55 56 // sThreadLocal.get() will return null unless you've called prepare(). 57 static final ThreadLocal<Looper> sThreadLocal = new ThreadLocal<Looper>(); 58 private static Looper sMainLooper; // guarded by Looper.class 59 60 final MessageQueue mQueue; 61 final Thread mThread; 62 volatile boolean mRun; 63 64 private Printer mLogging; 65 66 /** Initialize the current thread as a looper. 67 * This gives you a chance to create handlers that then reference 68 * this looper, before actually starting the loop. Be sure to call 69 * {@link #loop()} after calling this method, and end it by calling 70 * {@link #quit()}. 71 */ 72 public static void prepare() { 73 prepare(true); 74 } 75 76 private static void prepare(boolean quitAllowed) { 77 if (sThreadLocal.get() != null) { 78 throw new RuntimeException("Only one Looper may be created per thread"); 79 } 80 sThreadLocal.set(new Looper(quitAllowed)); 81 } 82 83 /** 84 * Initialize the current thread as a looper, marking it as an 85 * application's main looper. The main looper for your application 86 * is created by the Android environment, so you should never need 87 * to call this function yourself. See also: {@link #prepare()} 88 */ 89 public static void prepareMainLooper() { 90 prepare(false); 91 synchronized (Looper.class) { 92 if (sMainLooper != null) { 93 throw new IllegalStateException("The main Looper has already been prepared."); 94 } 95 sMainLooper = myLooper(); 96 } 97 } 98 99 /** Returns the application's main looper, which lives in the main thread of the application. 100 */ 101 public static Looper getMainLooper() { 102 synchronized (Looper.class) { 103 return sMainLooper; 104 } 105 } 106 107 /** 108 * Run the message queue in this thread. Be sure to call 109 * {@link #quit()} to end the loop. 110 */ 111 public static void loop() { 112 final Looper me = myLooper(); 113 if (me == null) { 114 throw new RuntimeException("No Looper; Looper.prepare() wasn't called on this thread."); 115 } 116 final MessageQueue queue = me.mQueue; 117 118 // Make sure the identity of this thread is that of the local process, 119 // and keep track of what that identity token actually is. 120 Binder.clearCallingIdentity(); 121 final long ident = Binder.clearCallingIdentity(); 122 123 for (;;) { 124 Message msg = queue.next(); // might block 125 if (msg == null) { 126 // No message indicates that the message queue is quitting. 127 return; 128 } 129 130 // This must be in a local variable, in case a UI event sets the logger 131 Printer logging = me.mLogging; 132 if (logging != null) { 133 logging.println(">>>>> Dispatching to " + msg.target + " " + 134 msg.callback + ": " + msg.what); 135 } 136 137 msg.target.dispatchMessage(msg); 138 139 if (logging != null) { 140 logging.println("<<<<< Finished to " + msg.target + " " + msg.callback); 141 } 142 143 // Make sure that during the course of dispatching the 144 // identity of the thread wasn't corrupted. 145 final long newIdent = Binder.clearCallingIdentity(); 146 if (ident != newIdent) { 147 Log.wtf(TAG, "Thread identity changed from 0x" 148 + Long.toHexString(ident) + " to 0x" 149 + Long.toHexString(newIdent) + " while dispatching to " 150 + msg.target.getClass().getName() + " " 151 + msg.callback + " what=" + msg.what); 152 } 153 154 msg.recycle(); 155 } 156 } 157 158 /** 159 * Return the Looper object associated with the current thread. Returns 160 * null if the calling thread is not associated with a Looper. 161 */ 162 public static Looper myLooper() { 163 return sThreadLocal.get(); 164 } 165 166 /** 167 * Control logging of messages as they are processed by this Looper. If 168 * enabled, a log message will be written to <var>printer</var> 169 * at the beginning and ending of each message dispatch, identifying the 170 * target Handler and message contents. 171 * 172 * @param printer A Printer object that will receive log messages, or 173 * null to disable message logging. 174 */ 175 public void setMessageLogging(Printer printer) { 176 mLogging = printer; 177 } 178 179 /** 180 * Return the {@link MessageQueue} object associated with the current 181 * thread. This must be called from a thread running a Looper, or a 182 * NullPointerException will be thrown. 183 */ 184 public static MessageQueue myQueue() { 185 return myLooper().mQueue; 186 } 187 188 private Looper(boolean quitAllowed) { 189 mQueue = new MessageQueue(quitAllowed); 190 mRun = true; 191 mThread = Thread.currentThread(); 192 } 193 194 /** 195 * Returns true if the current thread is this looper's thread. 196 * @hide 197 */ 198 public boolean isCurrentThread() { 199 return Thread.currentThread() == mThread; 200 } 201 202 /** 203 * Quits the looper. 204 * 205 * Causes the {@link #loop} method to terminate as soon as possible. 206 */ 207 public void quit() { 208 mQueue.quit(); 209 } 210 211 /** 212 * Posts a synchronization barrier to the Looper's message queue. 213 * 214 * Message processing occurs as usual until the message queue encounters the 215 * synchronization barrier that has been posted. When the barrier is encountered, 216 * later synchronous messages in the queue are stalled (prevented from being executed) 217 * until the barrier is released by calling {@link #removeSyncBarrier} and specifying 218 * the token that identifies the synchronization barrier. 219 * 220 * This method is used to immediately postpone execution of all subsequently posted 221 * synchronous messages until a condition is met that releases the barrier. 222 * Asynchronous messages (see {@link Message#isAsynchronous} are exempt from the barrier 223 * and continue to be processed as usual. 224 * 225 * This call must be always matched by a call to {@link #removeSyncBarrier} with 226 * the same token to ensure that the message queue resumes normal operation. 227 * Otherwise the application will probably hang! 228 * 229 * @return A token that uniquely identifies the barrier. This token must be 230 * passed to {@link #removeSyncBarrier} to release the barrier. 231 * 232 * @hide 233 */ 234 public int postSyncBarrier() { 235 return mQueue.enqueueSyncBarrier(SystemClock.uptimeMillis()); 236 } 237 238 239 /** 240 * Removes a synchronization barrier. 241 * 242 * @param token The synchronization barrier token that was returned by 243 * {@link #postSyncBarrier}. 244 * 245 * @throws IllegalStateException if the barrier was not found. 246 * 247 * @hide 248 */ 249 public void removeSyncBarrier(int token) { 250 mQueue.removeSyncBarrier(token); 251 } 252 253 /** 254 * Return the Thread associated with this Looper. 255 */ 256 public Thread getThread() { 257 return mThread; 258 } 259 260 /** @hide */ 261 public MessageQueue getQueue() { 262 return mQueue; 263 } 264 265 public void dump(Printer pw, String prefix) { 266 pw = PrefixPrinter.create(pw, prefix); 267 pw.println(this.toString()); 268 pw.println("mRun=" + mRun); 269 pw.println("mThread=" + mThread); 270 pw.println("mQueue=" + ((mQueue != null) ? mQueue : "(null")); 271 if (mQueue != null) { 272 synchronized (mQueue) { 273 long now = SystemClock.uptimeMillis(); 274 Message msg = mQueue.mMessages; 275 int n = 0; 276 while (msg != null) { 277 pw.println(" Message " + n + ": " + msg.toString(now)); 278 n++; 279 msg = msg.next; 280 } 281 pw.println("(Total messages: " + n + ")"); 282 } 283 } 284 } 285 286 public String toString() { 287 return "Looper{" + Integer.toHexString(System.identityHashCode(this)) + "}"; 288 } 289} 290