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.annotation.NonNull;
20import android.annotation.Nullable;
21import android.util.Log;
22import 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  */
54public 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