public abstract class

AsyncTask

extends Object
java.lang.Object
   ↳ mindroid.os.AsyncTask

Class Overview

AsyncTask enables proper and easy use of the UI thread. This class allows to perform background operations and publish results on the UI thread without having to manipulate threads and/or handlers.

AsyncTask is designed to be a helper class around Thread and Handler and does not constitute a generic threading framework. AsyncTasks should ideally be used for short operations (a few seconds at the most.) If you need to keep threads running for long periods of time, it is highly recommended you use the various APIs provided by the java.util.concurrent pacakge such as Executor, ThreadPoolExecutor.

An asynchronous task is defined by a computation that runs on a background thread and whose result is published on the UI thread. An asynchronous task is defined by 3 generic types, called Params, Progress and Result, and 4 steps, called onPreExecute, doInBackground, onProgressUpdate and onPostExecute.

Developer Guides

For more information about using tasks and threads, read the Processes and Threads developer guide.

Usage

AsyncTask must be subclassed to be used. The subclass will override at least one method ( doInBackground(Object[])), and most often will override a second one (onPostExecute(Object).)

Here is an example of subclassing:

 private class DownloadFilesTask extends AsyncTask<URL, Integer, Long> {
 	protected Long doInBackground(Object urls) {
 		int count = urls.length;
 		long totalSize = 0;
 		for (int i = 0; i < count; i++) {
 			totalSize += Downloader.downloadFile(urls[i]);
 			publishProgress((int) ((i / (float) count) * 100));
 			// Escape early if cancel() is called
 			if (isCancelled()) break;
 		}
 		return totalSize;
 	}
 
 	protected void onProgressUpdate(Integer... progress) {
 		setProgressPercent(progress[0]);
 	}
 
 	protected void onPostExecute(Long result) {
 		showDialog("Downloaded " + result + " bytes");
 	}
 }
 

Once created, a task is executed very simply:

 new DownloadFilesTask().execute(url1, url2, url3);
 

AsyncTask's generic types

The three types used by an asynchronous task are the following:

  1. Params, the type of the parameters sent to the task upon execution.
  2. Progress, the type of the progress units published during the background computation.
  3. Result, the type of the result of the background computation.

Not all types are always used by an asynchronous task. To mark a type as unused, simply use the type Void:

 private class MyTask extends AsyncTask<Void, Void, Void> { ... }
 

The 4 steps

When an asynchronous task is executed, the task goes through 4 steps:

  1. onPreExecute(), invoked on the UI thread immediately after the task is executed. This step is normally used to setup the task, for instance by showing a progress bar in the user interface.
  2. doInBackground(Object[]), invoked on the background thread immediately after onPreExecute() finishes executing. This step is used to perform background computation that can take a long time. The parameters of the asynchronous task are passed to this step. The result of the computation must be returned by this step and will be passed back to the last step. This step can also use publishProgress(Object[]) to publish one or more units of progress. These values are published on the UI thread, in the onProgressUpdate(Object[]) step.
  3. onProgressUpdate(Object[]), invoked on the UI thread after a call to publishProgress(Object[]). The timing of the execution is undefined. This method is used to display any form of progress in the user interface while the background computation is still executing. For instance, it can be used to animate a progress bar or show logs in a text field.
  4. onPostExecute(Object), invoked on the UI thread after the background computation finishes. The result of the background computation is passed to this step as a parameter.

Cancelling a task

A task can be cancelled at any time by invoking cancel(boolean). Invoking this method will cause subsequent calls to isCancelled() to return true. After invoking this method, onCancelled(Object), instead of onPostExecute(Object) will be invoked after ERROR(/#doInBackground(Object)) returns. To ensure that a task is cancelled as quickly as possible, you should always check the return value of isCancelled() periodically from ERROR(/#doInBackground(Object)), if possible (inside a loop for instance.)

Threading rules

There are a few threading rules that must be followed for this class to work properly:

Memory observability

AsyncTask guarantees that all callback calls are synchronized in such a way that the following operations are safe without explicit synchronizations.

Summary

Fields
public static final Executor SERIAL_EXECUTOR
public static final Executor THREAD_POOL_EXECUTOR
Public Constructors
AsyncTask()
Public Methods
final boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel execution of this task.

static void execute(Runnable runnable)
Convenience version of ERROR(/#execute(Object)) for use with a simple Runnable object.
AsyncTask execute(Object[] params)
AsyncTask executeOnExecutor(Executor executor, Object[] params)
final boolean isCancelled()
Returns true if this task was cancelled before it completed normally.
Protected Methods
abstract Object doInBackground(Object[] params)
Override this method to perform a computation on a background thread.
void onCancelled(Object result)

Runs on the UI thread after cancel(boolean) is invoked and ERROR(/#doInBackground(Object)) has finished.

void onCancelled()

Applications should preferably override onCancelled(Object).

void onPostExecute(Object result)

Runs on the UI thread after doInBackground(Object[]).

void onPreExecute()
Runs on the UI thread before doInBackground(Object[]).
void onProgressUpdate(Object[] values)
Runs on the UI thread after publishProgress(Object[]) is invoked.
final void publishProgress(Object[] values)
This method can be invoked from doInBackground(Object[]) to publish updates on the UI thread while the background computation is still running.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final Executor SERIAL_EXECUTOR

public static final Executor THREAD_POOL_EXECUTOR

Public Constructors

public AsyncTask ()

Public Methods

public final boolean cancel (boolean mayInterruptIfRunning)

Attempts to cancel execution of this task. This attempt will fail if the task has already completed, already been cancelled, or could not be cancelled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.

Calling this method will result in onCancelled(Object) being invoked on the UI thread after ERROR(/#doInBackground(Object)) returns. Calling this method guarantees that onPostExecute(Object) is never invoked. After invoking this method, you should check the value returned by isCancelled() periodically from ERROR(/#doInBackground(Object)) to finish the task as early as possible.

Parameters
mayInterruptIfRunning true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete.
Returns
  • false if the task could not be cancelled, typically because it has already completed normally; true otherwise

public static void execute (Runnable runnable)

Convenience version of ERROR(/#execute(Object)) for use with a simple Runnable object. See ERROR(/#execute(Object)) for more information on the order of execution.

public AsyncTask execute (Object[] params)

public AsyncTask executeOnExecutor (Executor executor, Object[] params)

public final boolean isCancelled ()

Returns true if this task was cancelled before it completed normally. If you are calling cancel(boolean) on the task, the value returned by this method should be checked periodically from ERROR(/#doInBackground(Object)) to end the task as soon as possible.

Returns
  • true if task was cancelled before it completed
See Also

Protected Methods

protected abstract Object doInBackground (Object[] params)

Override this method to perform a computation on a background thread. The specified parameters are the parameters passed to execute(Object[]) by the caller of this task. This method can call publishProgress(Object[]) to publish updates on the UI thread.

Parameters
params The parameters of the task.
Returns
  • A result, defined by the subclass of this task.

protected void onCancelled (Object result)

Runs on the UI thread after cancel(boolean) is invoked and ERROR(/#doInBackground(Object)) has finished.

The default implementation simply invokes onCancelled() and ignores the result. If you write your own implementation, do not call super.onCancelled(result).

Parameters
result The result, if any, computed in ERROR(/#doInBackground(Object)), can be null

protected void onCancelled ()

Applications should preferably override onCancelled(Object). This method is invoked by the default implementation of onCancelled(Object).

Runs on the UI thread after cancel(boolean) is invoked and ERROR(/#doInBackground(Object)) has finished.

protected void onPostExecute (Object result)

Runs on the UI thread after doInBackground(Object[]). The specified result is the value returned by doInBackground(Object[]).

This method won't be invoked if the task was cancelled.

Parameters
result The result of the operation computed by doInBackground(Object[]).

protected void onPreExecute ()

protected void onProgressUpdate (Object[] values)

Runs on the UI thread after publishProgress(Object[]) is invoked. The specified values are the values passed to publishProgress(Object[]).

Parameters
values The values indicating progress.

protected final void publishProgress (Object[] values)

This method can be invoked from doInBackground(Object[]) to publish updates on the UI thread while the background computation is still running. Each call to this method will trigger the execution of onProgressUpdate(Object[]) on the UI thread. onProgressUpdate(Object[]) will note be called if the task has been canceled.

Parameters
values The progress values to update the UI with.