The previous guide, which teaches you to Specify the code to
run on a thread, shows how to define a task that executes on a separate
thread. If you only want to run the task once, this may be all you need. If you want
to run a task repeatedly on different sets of data, but you only need one execution running at a
time, an IntentService
suits your needs. To automatically run tasks
as resources become available, or to allow multiple tasks to run at the same time (or both),
you need to provide a managed collection of threads. To do this, use an instance of
ThreadPoolExecutor
, which runs a task from a queue when a thread
in its pool becomes free. To run a task, all you have to do is add it to the queue.
A thread pool can run multiple parallel instances of a task, so you should ensure that your
code is thread-safe. Enclose variables that can be accessed by more than one thread in a
synchronized
block. This approach will prevent one thread from reading the variable
while another is writing to it. Typically, this situation arises with static variables, but it
also occurs in any object that is only instantiated once. To learn more about this, read the
Processes and threads overview guide.
Define the thread pool class
Instantiate ThreadPoolExecutor
in its own class. Within this class,
do the following:
- Use static variables for thread pools
-
You may only want a single instance of a thread pool for your app, in order to have a
single control point for restricted CPU or network resources. If you have different
Runnable
types, you may want to have a thread pool for each one, but each of these can be a single instance. For example, you can add this as part of your global field declarations (for Kotlin we can create an object):Kotlin
// Creates a single static instance of PhotoManager object PhotoManager { ... }
Java
public class PhotoManager { ... static { ... // Creates a single static instance of PhotoManager sInstance = new PhotoManager(); } ...
- Use a private constructor
-
Making the constructor private ensures that it is a singleton, which means that you don't
have to enclose accesses to the class in a
synchronized
block (for Kotlin it is not necessary to have a private constructor because this is defined as an object so will only be initialised once):Kotlin
object PhotoManager { ... }
Java
public class PhotoManager { ... /** * Constructs the work queues and thread pools used to download * and decode images. Because the constructor is marked private, * it's unavailable to other classes, even in the same package. */ private PhotoManager() { ... }
- Start your tasks by calling methods in the thread pool class.
-
Define a method in the thread pool class that adds a task to a thread pool's queue. For
example:
Kotlin
object PhotoManager { ... fun startDownload(imageView: PhotoView, downloadTask: DownloadTask, cacheFlag: Boolean) = decodeThreadPool.execute(downloadTask.getHTTPDownloadRunnable()) ... }
Java
public class PhotoManager { ... // Called by the PhotoView to get a photo static public PhotoTask startDownload( PhotoView imageView, DownloadTask downloadTask, boolean cacheFlag) { ... // Adds a download task to the thread pool for execution sInstance. downloadThreadPool. execute(downloadTask.getHTTPDownloadRunnable()); ... }
-
Instantiate a
Handler
in the constructor and attach it to your app's UI thread. -
A
Handler
allows your app to safely call the methods of UI objects such asView
objects. Most UI objects may only be safely altered from the UI thread. This approach is described in more detail in the lesson Communicate with the UI thread. For example:Kotlin
object PhotoManager { ... private val handler = object : Handler(Looper.getMainLooper()) { /* * handleMessage() defines the operations to perform when * the Handler receives a new Message to process. */ override fun handleMessage(msg: Message?) { ... } ... } }
Java
private PhotoManager() { ... // Defines a Handler object that's attached to the UI thread handler = new Handler(Looper.getMainLooper()) { /* * handleMessage() defines the operations to perform when * the Handler receives a new Message to process. */ @Override public void handleMessage(Message inputMessage) { ... } ... } }
Determine the thread pool parameters
Once you have the overall class structure, you can start defining the thread pool. To
instantiate a ThreadPoolExecutor
object, you need the
following values:
- Initial pool size and maximum pool size
-
The initial number of threads to allocate to the pool, and the maximum allowable number.
The number of threads you can have in a thread pool depends primarily on the number of cores
available for your device. This number is available from the system environment:
Kotlin
object PhotoManager { ... /* * Gets the number of available cores * (not always the same as the maximum number of cores) */ private val NUMBER_OF_CORES = Runtime.getRuntime().availableProcessors() }
Java
public class PhotoManager { ... /* * Gets the number of available cores * (not always the same as the maximum number of cores) */ private static int NUMBER_OF_CORES = Runtime.getRuntime().availableProcessors(); }
availableProcessors()
returns the number of active cores, which may be less than the total number of cores. - Keep alive time and time unit
-
The duration that a thread will remain idle before it shuts down. The duration is
interpreted by the time unit value, one of the constants defined in
TimeUnit
. - A queue of tasks
-
The incoming queue from which
ThreadPoolExecutor
takesRunnable
objects. To start code on a thread, a thread pool manager takes aRunnable
object from a first-in, first-out queue and attaches it to the thread. You provide this queue object when you create the thread pool, using any queue class that implements theBlockingQueue
interface. To match the requirements of your app, you can choose from the available queue implementations; to learn more about them, see the class overview forThreadPoolExecutor
. This example uses theLinkedBlockingQueue
class:Kotlin
object PhotoManager { ... // Instantiates the queue of Runnables as a LinkedBlockingQueue private val decodeWorkQueue: BlockingQueue<Runnable> = LinkedBlockingQueue<Runnable>() ... }
Java
public class PhotoManager { ... private PhotoManager() { ... // A queue of Runnables private final BlockingQueue<Runnable> decodeWorkQueue; ... // Instantiates the queue of Runnables as a LinkedBlockingQueue decodeWorkQueue = new LinkedBlockingQueue<Runnable>(); ... } ... }
Create a thread pool
To create a pool of threads, instantiate a thread pool manager by calling
ThreadPoolExecutor()
.
This creates and manages a constrained group of threads. Because the initial pool size and
the maximum pool size are the same, ThreadPoolExecutor
creates
all of the thread objects when it is instantiated. For example:
Kotlin
object PhotoManager { ... // Sets the amount of time an idle thread waits before terminating private const val KEEP_ALIVE_TIME = 1L // Sets the Time Unit to seconds private val KEEP_ALIVE_TIME_UNIT = TimeUnit.SECONDS // Creates a thread pool manager private val decodeThreadPool: ThreadPoolExecutor = ThreadPoolExecutor( NUMBER_OF_CORES, // Initial pool size NUMBER_OF_CORES, // Max pool size KEEP_ALIVE_TIME, KEEP_ALIVE_TIME_UNIT, decodeWorkQueue )
Java
private PhotoManager() { ... // Sets the amount of time an idle thread waits before terminating private static final int KEEP_ALIVE_TIME = 1; // Sets the Time Unit to seconds private static final TimeUnit KEEP_ALIVE_TIME_UNIT = TimeUnit.SECONDS; // Creates a thread pool manager decodeThreadPool = new ThreadPoolExecutor( NUMBER_OF_CORES, // Initial pool size NUMBER_OF_CORES, // Max pool size KEEP_ALIVE_TIME, KEEP_ALIVE_TIME_UNIT, decodeWorkQueue); }
Alternatively, if you don't want to manage the details of the thread pool sizing, you may find the Executors factory methods for creating a single thread executor or the work stealing executor more convenient.
More information
To learn more about multi-threaded operations on Android, see the Process and threads overview guide.
Sample app
To try out the concepts in this guide, download ThreadSample
.