The
Handler class is fundamental to the infrastructure of Android apps—together with Looper. It underpins everything that the main thread does—including the invocation of the Activity lifecycle methods.
While Looper takes care of dispatching work on its message-loop thread, Handler provides the means to add work to the message queue belonging to a Looper.
We can create a Handler to submit work to be processed on the main thread simply by creating a new instance of Handler from an Activity lifecycle method such as onCreate, shown as follows:
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Handler handler = new Handler();
// …
}We could also be explicit that we want to submit work to the main thread by passing a reference to the main Looper instance into the Handler constructor.
Handler handler = new Handler(Looper.getMainLooper());
Exactly what we mean by "work" can be described by subclasses of java.lang.Runnable, or instances of android.os.Message. We can post Runnables to a Handler instance or send Messages to it, and it will add them to the queue belonging to the associated Looper instance.
We can post work to a Handler very simply, for example, by creating an anonymous inner Runnable:
handler.post(new Runnable(){
public void run() {
// do some work on the main thread.
}
});The Looper instance to which the Handler is bound works its way through the queue, executing each Runnable as soon as possible. Posting with the post method simply adds a new Runnable at the end of the queue.
If we want our Runnable to take priority over anything currently in the queue, we can post it to the front of the queue ahead of existing work:
handler.postAtFrontOfQueue(new Runnable(){
public void run() {
// do some work on the main thread.
}
});In a single-threaded application it might seem like there is not a whole lot to be gained from posting work to the main thread like this, but breaking things down into small tasks that can be interleaved and potentially reordered is very useful for maintaining responsiveness.
This becomes clear if we consider the question: what if we want to schedule some work in 10 seconds time? One way to do this would be to Thread.sleep the main thread for 10 seconds, but that would mean the main thread can't do anything else in the meantime. Also, remember that we must never block the main thread! The alternative is to post a delayed Runnable to the Handler.
handler.postDelayed(new Runnable(){
public void run() {
// do some work on the main thread
// in 10 seconds time
}
}, TimeUnit.SECONDS.toMillis(10));We can still post additional work for execution in the meantime, and our delayed Runnable instance will execute after the specified delay. Note that we're using the TimeUnit class from the java.lang.concurrent package to convert seconds to milliseconds.
A further scheduling option for posted work is postAtTime, which schedules Runnable to execute at a particular time relative to the system uptime (how long it has been since the system booted):
handler.postAtTime(new Runnable(){
public void run() {
// … do some work on the main thread
}
}, SystemClock.uptimeMillis() + TimeUnit.SECONDS.toMillis(10));Since postDelayed is implemented in terms of an offset from the SystemClock uptime, it is usually easier to just use postDelayed.
Since we instantiated our Handler on the main thread, all work submitted to it executes on the main thread. This means that we must not submit long running operations to this particular Handler, but we can safely interact with the user interface:
handler.post(new Runnable(){
public void run() {
TextView text = (TextView) findViewById(R.id.text);
text.setText("updated on the UI thread");
}
});This applies regardless of which thread posts the Runnable, which makes Handler an ideal way to send the results of work performed by other threads to the main thread.
Thread thread = new Thread(){ public void run(){ final BigInteger result = calculatePrime(500); handler.post(new Runnable(){ public void run(){ TextView text = (TextView) findViewById(R.id.text); text.setText(result.toString()); } }); } }; thread.setPriority(Thread.MIN_PRIORITY); thread.start();
Handler is so fundamental that it is integrated right into the View class hierarchy, so we can rewrite the last example as follows:
final TextView text = (TextView) findViewById(R.id.text); Thread thread = new Thread(){ public void run(){ final BigInteger result = calculatePrime(500); text.post(new Runnable(){ public void run() { text.setText(result.toString()); } }); } }; thread.setPriority(Thread.MIN_PRIORITY); thread.start();
For comparison, both of the previous examples are roughly equivalent to the following AsyncTask code:
new AsyncTask<Void,Void,BigInteger>(){
public BigInteger doInBackground(Void… params){
return calculatePrime(500);
}
public void onPostExecute(BigInteger result){
TextView text = (TextView) findViewById(R.id.text);
text.setText(result.toString());
}
}.execute();When writing code in an Activity class, there is an alternative way of executing a Runnable on the main thread using the runOnUiThread method of Activity. If invoked from a background thread, the Runnable will be posted to a Handler instance attached to the main thread. If invoked from the main thread, the Runnable will be executed immediately.
We can cancel a pending operation by removing a posted Runnable callback from the queue.
final Runnable runnable = new Runnable(){
public void run() {
// … do some work
}
};
handler.postDelayed(runnable, TimeUnit.SECONDS.toMillis(10));
Button cancel = (Button) findViewById(R.id.cancel);
cancel.setOnClickListener(new OnClickListener(){
public void onClick(View v) {
handler.removeCallbacks(runnable);
}
});Notice that in order to be able to specify what to remove, we must keep a reference to the Runnable instance, and that cancellation applies only to pending tasks—it does not attempt to stop a Runnable that is already mid-execution.
When we post a Runnable, we can—as seen in the previous examples—define the work at the call site with an anonymous Runnable. As such, the Handler does not know in advance what kind of work it might be asked to perform.
If we often need to perform the same work from different call sites we could define a static or top-level Runnable class that we can instantiate from different call sites.
Alternatively, we can turn the approach on its head by sending Messages to a Handler, and defining the Handler to react appropriately to different Messages.
Taking a simple example, let's say we want our Handler to display hello or goodbye, depending on what type of Message it receives. To do that, we'll extend Handler and override its
handleMessage method.
public static class SpeakHandler extends Handler {
public static final int SAY_HELLO = 0;
public static final int SAY_BYE = 1;
@Override
public void handleMessage(Message msg) {
switch(msg.what) {
case SAY_HELLO:
sayWord("hello"); break;
case SAY_BYE:
sayWord("goodbye"); break;
default:
super.handleMessage(msg);
}
}
private void sayWord(String word) { … }
}Here we've implemented the handleMessage method to expect messages with two different what values and react accordingly.
To attach an instance of our Handler to the main thread, we simply instantiate it from any method which runs on the main thread:
private Handler handler; protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); handler = new SpeakHandler(); // … }
Remember that we can send Messages to this Handler from any thread, and they will be processed by the main thread. We send Messages to our Handler as shown:
handler.sendEmptyMessage(SAY_HELLO);
Messages may also carry an object payload as context for the execution of the message. Let's extend our example to allow our Handler to say any word that the message sender wants:
public static class SpeakHandler extends Handler {
public static final int SAY_HELLO = 0;
public static final int SAY_BYE = 1;
public static final int SAY_WORD = 2;
@Override
public void handleMessage(Message msg) {
switch(msg.what) {
case SAY_HELLO:
sayWord("hello"); break;
case SAY_BYE:
sayWord("goodbye"); break;
case SAY_WORD:
sayWord((String)msg.obj); break;
default:
super.handleMessage(msg);
}
}
private void sayWord(String word) { … }
}Within our handleMessage method, we can access the payload of the Message directly by accessing the public obj property. The Message payload can be set easily via alternative static obtain methods.
handler.sendMessage(
Message.obtain(handler, SpeakHandler.SAY_WORD, "tada!"));While it should be quite clear what this code is doing, you might be wondering why we didn't create a new instance of Message by invoking its constructor, and instead invoked its static method obtain.
The reason is efficiency. Messages are used only briefly—we instantiate, dispatch, handle, and then discard them. So if we create new instances for each we are creating work for the garbage collector.
Garbage collection is expensive, and the Android platform goes out of its way to minimize object allocation whenever it can. While we can instantiate a new Message object if we wish, the recommended approach is to obtain one, which re-uses Message instances from a pool and cuts down on garbage collection overhead.
Just as we can schedule Runnables with the variants of the post method, we can schedule Messages with variants of send.
handler.sendMessageAtFrontOfQueue(msg); handler.sendMessageAtTime(msg, time); handler.sendMessageDelayed(msg, delay);
There are also empty-message variants for convenience, when we don't have a payload.
handler.sendEmptyMessageAtTime(what, time); handler.sendEmptyMessageDelayed(what, delay);
Canceling sent Messages is also possible, and actually easier than canceling posted Runnables because we don't have to keep a reference to the Messages that we might want to cancel—instead we can just cancel Messages by their what value.
handler.removeMessages(SpeakHandler.SAY_WORD);
Note that just as with posted Runnables, Message cancellation only removes pending operations from the queue—it does not attempt to stop an operation which is already being executed.
So far we subclassed Handler to override its handleMessage method, but that isn't our only option. We can prefer composition over inheritance by passing an instance of Handler.Callback during Handler construction.
public static class Speaker implements Handler.Callback {
public static final int SAY_HELLO = 0;
public static final int SAY_BYE = 1;
public static final int SAY_WORD = 2;
@Override
public boolean handleMessage(Message msg) {
switch(msg.what) {
case SAY_HELLO:
sayWord("hello"); break;
case SAY_BYE:
sayWord("goodbye"); break;
case SAY_WORD:
sayWord((String)msg.obj); break;
default:
return false;
}
return true;
}
private void sayWord(String word) { … }
}Notice that the signature of handleMessage is slightly different here—we must return a boolean indicating whether or not the Message was handled. To create a Handler that uses our Callback, simply pass the Callback during Handler construction.
Handler handler = new Handler(new Speaker());
If we return false from the handleMessage method of our Callback, the Handler will invoke its own handleMessage method, so we could choose to use a combination of inheritance and composition to implement default behavior in a Handler subclass, and mix in special behavior by passing in an instance of Handler.Callback.
public static class SpeakHandler extends Handler {
public static final int SAY_HELLO = 0;
public static final int SAY_BYE = 1;
public SpeakHandler(Callback callback) {
super(callback);
}
@Override
public void handleMessage(Message msg) {
switch(msg.what) {
case SAY_HELLO:
sayWord("hello"); break;
case SAY_BYE:
sayWord("goodbye"); break;
default:
super.handleMessage(msg);
}
}
private void sayWord(String word) { … }
}
public static class Speaker implements Handler.Callback {
public static final int SAY_WORD = 2;
@Override
public boolean handleMessage(Message msg) {
if (msg.what == SAY_WORD) {
sayWord((String)msg.obj);
return true;
}
return false;
}
private void sayWord(String word) { … }
}
Handler h = new SpeakHandler(new Speaker());
h.sendMessage(Message.obtain(handler, Speaker.SAY_WORD, "!?"));With SpeakHandler set up like this, we can easily send Messages from any thread to update the user interface. Sending from a background thread or the main thread itself is exactly the same—just obtain a Message and send it via SpeakHandler.
Let's extend our example to bind the app to a network socket and echo lines of text it receives from the socket to the screen. Listening for lines of text from the network socket is a blocking operation, so we must not do it from the main thread.
We'll start a background thread, then bind the server socket and wait for a client to connect over the network. When this background thread receives text from the socket, it will send it in a Message to the SpeakHandler instance, which will update the user interface on the main thread.
static class Parrot extends Thread {
private Handler handler;
private InetAddress address;
private ServerSocket server;
public Parrot(InetAddress address, Handler handler) {
this.handler = handler;
this.address = address;
setPriority(Thread.MIN_PRIORITY);
}
public void run() {
try {
server = new ServerSocket(4444, 1, address);
while (true) {
Socket client = server.accept();
handler.sendMessage(Message.obtain(handler,
SpeakHandler.SAY_HELLO));
BufferedReader in = new BufferedReader(
new InputStreamReader(
client.getInputStream()));
String word;
while (!"bye".equals(word = in.readLine())) {
handler.sendMessage(Message.obtain(handler,
SpeakHandler.SAY_WORD, word));
}
client.close();
handler.sendMessage(
Message.obtain(
handler, SpeakHandler.SAY_BYE));
}
} catch (Exception exc) {
Log.e(TAG, exc.getMessage(), exc);
}
}
}Let's have a quick look at the key elements of the run method. First, we bind a socket to port 4444 (any port higher than 1024 will do) on the given address, which allows us to listen for incoming connections. The second parameter says we're only allowing one connection at a time:
server = new ServerSocket(4444, 1, address);
We loop forever, or until an exception is thrown. Inside the loop we wait for a client to connect:
Socket client = server.accept();
The accept method blocks, so our background thread is suspended until a client makes a connection. As soon as a client connects, we send a SAY_HELLO message to our Handler, so the main thread will update the user interface for us:
handler.sendMessage(
Message.obtain(handler, SpeakHandler.SAY_HELLO));Next, we wrap a buffering reader around our socket's input stream, and loop on its readLine method, which blocks until a line of text is available.
BufferedReader in = new BufferedReader(
new InputStreamReader(client.getInputStream()));
String word;
while (!"bye".equals(word = in.readLine())) {When we receive some text from the socket, we send it in a Message to our Handler.
handler.sendMessage(
Message.obtain(handler, SpeakHandler.SAY_WORD, word));If we receive bye, we'll break out of the loop, disconnect this client, and say goodbye:
client.close();
handler.sendMessage(
Message.obtain(handler, SpeakHandler.SAY_BYE));To obtain the address of the device, we can use the Wi-Fi service. We'll need to convert the value we get from the Wi-Fi service to an instance of the InetAddress class, elided here for brevity.
private InetAddress getAddress() {
WifiManager wm = (WifiManager)getSystemService(WIFI_SERVICE);
return asInetAddress(wm.getConnectionInfo().getIpAddress());
}Binding the socket and using the Wi-Fi service requires permissions to be requested in the Android manifest:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission
android:name="android.permission.ACCESS_WIFI_STATE"/>Finally we need to create and start Parrot in a suitable Activity lifecycle method, for example, onResume. To make it easy to connect, we'll display the address and port on the screen.
TextView view = (TextView) findViewById(R.id.speak);
if (parrot == null) {
InetAddress address = getAddress();
parrot = new Parrot(address, handler);
parrot.start();
view.setText("telnet " + address.getHostAddress() + " 4444");
}We should also remove pending messages in onPause, and disconnect the socket if the Activity is finishing—the complete code is available for download from the accompanying website.
When the app starts, you'll see a message on the device screen like telnet 192.168.0.4 4444. To connect and send messages to your device's screen, open the command prompt on your development computer and copy the text from your device screen to the command prompt.
You should see the following output:
Trying 192.168.0.4... Connected to 192.168.0.4. Escape character is '^]'.
Congratulations! You're connected. Enter some words in the command prompt and they'll appear on your device screen. Enter bye to disconnect.
It is worth spending a few moments to consider the difference between posting Runnables and sending Messages.
The runtime difference mostly comes down to efficiency. Creating new instances of Runnable each time we want our Handler to do something adds garbage collection overhead, while sending messages re-uses Message instances, which are sourced from an application-wide pool.
The difference at development time is between allowing code at the call site to specify arbitrary work for the Handler to do (Runnable.run) potentially spreading similar code throughout the codebase, versus the Handler defining the work it is prepared to do in a single place (Handler.handleMessage).
For prototyping and small one-offs, posting Runnables is quick and easy, while the advantages of sending Messages tend to grow with the size of the application. It should be said that Message sending is more "The Android Way", and is used throughout the platform to keep garbage to a minimum and apps running smoothly.
So far we only really considered Handler as a way to request work be performed on the main thread—we've submitted work from the main thread to itself, and from a background thread to the main thread.
In fact we can bind Handlers to any thread we create, and in doing so allow any thread to submit work for another thread to execute. For example, we can submit work from the main thread to a background thread or from one background thread to another.
We saw one way of setting up a Looper thread with a Handler in the Understanding Looper section earlier in this chapter, but there's an easier way using a class provided by the SDK for exactly this purpose, android.os.HandlerThread.
When we create a HandlerThread, we specify two things: a name for the thread, which can be helpful when debugging; and its priority, which must be selected from the set of static values in the android.os.Process class.
HandlerThread thread =
new HandlerThread("bg", Process.THREAD_PRIORITY_BACKGROUND);Thread priorities in Android are mapped onto Linux "nice" levels, which govern how often a thread gets to run.
In addition to prioritization, Android limits CPU resources using Linux cgroups. Threads that are of background priority are moved into the bg_non_interactive cgroup, which is limited to 5 percent of available CPU if threads in other groups are busy.
Adding THREAD_PRIORITY_MORE_FAVORABLE to THREAD_PRIORITY_BACKGROUND when configuring your HandlerThread moves the thread into the default cgroup, but always consider whether it is really necessary—it often isn't!
HandlerThread extends java.lang.Thread, and we must start() it before it will actually begin processing its queue:
thread.start();
Now we need a Handler through which we can pass work to our HandlerThread. So we create a new instance, but this time we parameterize the constructor with the Looper associated with our HandlerThread.
Handler handler = new Handler(thread.getLooper());
That's all there is to it—we can now post Runnables for our HandlerThread to execute:
handler.post(new Runnable(){
public void run() {
// ... do some work in the background thread
}
});To send Messages to our HandlerThread, we'll need to override handleMessage or provide a Callback via the alternate Handler constructor:
Handler.Callback callback = new Handler.Callback(){ … };
Handler handler = new Handler(thread.getLooper(), callback);If we create a HandlerThread to do background work for a specific Activity, we will want to tie the HandlerThread's lifecycle closely to that of the Activity to prevent resource leaks.
A HandlerThread can be shut down by invoking quit, which will stop the HandlerThread from processing any more work from its queue. A quitSafely method was added at API level 18, which causes the HandlerThread to process all remaining tasks before shutting down. Once a HandlerThread has been told to shut down, it will not accept any further tasks.
Just as we did in the previous chapter with AsyncTask, we can use the Activity lifecycle methods to determine when we should quit the HandlerThread.
private HandlerThread thread;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
thread = new HandlerThread( … );
}
protected void onPause() {
super.onPause();
if ((thread != null) && (isFinishing()))
thread.quit();
}