am d4289c6e: am c84b3603: am 8dd6275e: Android Training: Multiple Threads (4c59230a) · Commits · e / os / android_frameworks_base

docs/html/training/multiple-threads/communicate-ui.jd

0 → 100644

+263 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Communicating with the UI Thread

			trainingnavtop=true
			@jd:body

			<div id="tb-wrapper">
			<div id="tb">

			<!-- table of contents -->
			<h2>This lesson teaches you to</h2>
			<ol>
			<li><a href="#Handler">Define a Handler on the UI Thread</a></li>
			<li><a href="#MoveValues">Move Data from a Task to the UI Thread</a>
			</ol>

			<h2>You should also read</h2>
			<ul>
			<li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
			</ul>


			<h2>Try it out</h2>
			<div class="download-box">
			<a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
			<p class="filename">ThreadSample.zip</p>
			</div>

			</div>
			</div>
			<p>
			In the previous lesson you learned how to start a task on a thread managed by
			{@link java.util.concurrent.ThreadPoolExecutor}. This final lesson shows you how to send data
			from the task to objects running on the user interface (UI) thread. This feature allows your
			tasks to do background work and then move the results to UI elements such as bitmaps.
			</p>
			<p>
			Every app has its own special thread that runs UI objects such as {@link android.view.View}
			objects; this thread is called the UI thread. Only objects running on the UI thread have access
			to other objects on that thread. Because tasks that you run on a thread from a thread pool
			<em>aren't</em> running on your UI thread, they don't have access to UI objects. To move data
			from a background thread to the UI thread, use a {@link android.os.Handler} that's
			running on the UI thread.
			</p>
			<h2 id="Handler">Define a Handler on the UI Thread</h2>
			<p>
			{@link android.os.Handler} is part of the Android system's framework for managing threads. A
			{@link android.os.Handler} object receives messages and runs code to handle the messages.
			Normally, you create a {@link android.os.Handler} for a new thread, but you can
			also create a {@link android.os.Handler} that's connected to an existing thread.
			When you connect a {@link android.os.Handler} to your UI thread, the code that handles messages
			runs on the UI thread.
			</p>
			<p>
			Instantiate the {@link android.os.Handler} object in the constructor for the class that
			creates your thread pools, and store the object in a global variable. Connect it to the UI
			thread by instantiating it with the {@link android.os.Handler#Handler(Looper) Handler(Looper)}
			constructor. This constructor uses a {@link android.os.Looper} object, which is another part of
			the Android system's thread management framework. When you instantiate a
			{@link android.os.Handler} based on a particular {@link android.os.Looper} instance, the
			{@link android.os.Handler} runs on the same thread as the {@link android.os.Looper}.
			For example:
			</p>
			<pre>
			private PhotoManager() {
			...
			// Defines a Handler object that's attached to the UI thread
			mHandler = new Handler(Looper.getMainLooper()) {
			...
			</pre>
			<p>
			Inside the {@link android.os.Handler}, override the {@link android.os.Handler#handleMessage
			handleMessage()} method. The Android system invokes this method when it receives a new message
			for a thread it's managing; all of the {@link android.os.Handler} objects for a particular
			thread receive the same message. For example:
			</p>
			<pre>
			/*
			* handleMessage() defines the operations to perform when
			* the Handler receives a new Message to process.
			*/
			@Override
			public void handleMessage(Message inputMessage) {
			// Gets the image task from the incoming Message object.
			PhotoTask photoTask = (PhotoTask) inputMessage.obj;
			...
			}
			...
			}
			}
			The next section shows how to tell the {@link android.os.Handler} to move data.
			</pre>
			<h2 id="MoveValues">Move Data from a Task to the UI Thread</h2>
			<p>
			To move data from a task object running on a background thread to an object on the UI thread,
			start by storing references to the data and the UI object in the task object. Next, pass the
			task object and a status code to the object that instantiated the {@link android.os.Handler}.
			In this object, send a {@link android.os.Message} containing the status and the task object to
			the {@link android.os.Handler}. Because {@link android.os.Handler} is running on the UI thread,
			it can move the data to the UI object.

			<h3>Store data in the task object</h3>
			<p>
			For example, here's a {@link java.lang.Runnable}, running on a background thread, that decodes a
			{@link android.graphics.Bitmap} and stores it in its parent object <code>PhotoTask</code>.
			The {@link java.lang.Runnable} also stores the status code <code>DECODE_STATE_COMPLETED</code>.
			</p>
			<pre>
			// A class that decodes photo files into Bitmaps
			class PhotoDecodeRunnable implements Runnable {
			...
			PhotoDecodeRunnable(PhotoTask downloadTask) {
			mPhotoTask = downloadTask;
			}
			...
			// Gets the downloaded byte array
			byte[] imageBuffer = mPhotoTask.getByteBuffer();
			...
			// Runs the code for this task
			public void run() {
			...
			// Tries to decode the image buffer
			returnBitmap = BitmapFactory.decodeByteArray(
			imageBuffer,
			0,
			imageBuffer.length,
			bitmapOptions
			);
			...
			// Sets the ImageView Bitmap
			mPhotoTask.setImage(returnBitmap);
			// Reports a status of "completed"
			mPhotoTask.handleDecodeState(DECODE_STATE_COMPLETED);
			...
			}
			...
			}
			...
			</pre>
			<p>
			<code>PhotoTask</code> also contains a handle to the {@link android.widget.ImageView} that
			displays the {@link android.graphics.Bitmap}. Even though references to
			the {@link android.graphics.Bitmap} and {@link android.widget.ImageView} are in the same object,
			you can't assign the {@link android.graphics.Bitmap} to the {@link android.widget.ImageView},
			because you're not currently running on the UI thread.
			</p>
			<p>
			Instead, the next step is to send this status to the <code>PhotoTask</code> object.
			</p>
			<h3>Send status up the object hierarchy</h3>
			<p>
			<code>PhotoTask</code> is the next higher object in the hierarchy. It maintains references to
			the decoded data and the {@link android.view.View} object that will show the data. It receives
			a status code from <code>PhotoDecodeRunnable</code> and passes it along to the object that
			maintains thread pools and instantiates {@link android.os.Handler}:
			</p>
			<pre>
			public class PhotoTask {
			...
			// Gets a handle to the object that creates the thread pools
			sPhotoManager = PhotoManager.getInstance();
			...
			public void handleDecodeState(int state) {
			int outState;
			// Converts the decode state to the overall state.
			switch(state) {
			case PhotoDecodeRunnable.DECODE_STATE_COMPLETED:
			outState = PhotoManager.TASK_COMPLETE;
			break;
			...
			}
			...
			// Calls the generalized state method
			handleState(outState);
			}
			...
			// Passes the state to PhotoManager
			void handleState(int state) {
			/*
			* Passes a handle to this task and the
			* current state to the class that created
			* the thread pools
			*/
			sPhotoManager.handleState(this, state);
			}
			...
			}
			</pre>
			<h3>Move data to the UI</h3>
			<p>
			From the <code>PhotoTask</code> object, the <code>PhotoManager</code> object receives a status
			code and a handle to the <code>PhotoTask</code> object. Because the status is
			<code>TASK_COMPLETE</code>, creates a {@link android.os.Message} containing the state and task
			object and sends it to the {@link android.os.Handler}:
			</p>
			<pre>
			public class PhotoManager {
			...
			// Handle status messages from tasks
			public void handleState(PhotoTask photoTask, int state) {
			switch (state) {
			...
			// The task finished downloading and decoding the image
			case TASK_COMPLETE:
			/*
			* Creates a message for the Handler
			* with the state and the task object
			*/
			Message completeMessage =
			mHandler.obtainMessage(state, photoTask);
			completeMessage.sendToTarget();
			break;
			...
			}
			...
			}
			</pre>
			<p>
			Finally, {@link android.os.Handler#handleMessage Handler.handleMessage()} checks the status
			code for each incoming {@link android.os.Message}. If the status code is
			<code>TASK_COMPLETE</code>, then the task is finished, and the <code>PhotoTask</code> object
			in the {@link android.os.Message} contains both a {@link android.graphics.Bitmap} and an
			{@link android.widget.ImageView}. Because
			{@link android.os.Handler#handleMessage Handler.handleMessage()} is
			running on the UI thread, it can safely move the {@link android.graphics.Bitmap} to the
			{@link android.widget.ImageView}:
			</p>
			<pre>
			private PhotoManager() {
			...
			mHandler = new Handler(Looper.getMainLooper()) {
			@Override
			public void handleMessage(Message inputMessage) {
			// Gets the task from the incoming Message object.
			PhotoTask photoTask = (PhotoTask) inputMessage.obj;
			// Gets the ImageView for this task
			PhotoView localView = photoTask.getPhotoView();
			...
			switch (inputMessage.what) {
			...
			// The decoding is done
			case TASK_COMPLETE:
			/*
			* Moves the Bitmap from the task
			* to the View
			*/
			localView.setImageBitmap(photoTask.getImage());
			break;
			...
			default:
			/*
			* Pass along other messages from the UI
			*/
			super.handleMessage(inputMessage);
			}
			...
			}
			...
			}
			...
			}
			...
			}
			</pre>

docs/html/training/multiple-threads/create-threadpool.jd

0 → 100644

+238 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Creating a Manager for Multiple Threads

			trainingnavtop=true
			@jd:body

			<div id="tb-wrapper">
			<div id="tb">

			<!-- table of contents -->
			<h2>This lesson teaches you to</h2>
			<ol>
			<li><a href="#ClassStructure">Define the Thread Pool Class</a>
			<li><a href="#PoolParameters">Determine the Thread Pool Parameters</a></li>
			<li><a href="#ThreadPool">Create a Pool of Threads</a></li>
			</ol>

			<!-- other docs (NOT javadocs) -->
			<h2>You should also read</h2>
			<ul>
			<li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
			</ul>

			<h2>Try it out</h2>
			<div class="download-box">
			<a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
			<p class="filename">ThreadSample.zip</p>
			</div>


			</div>
			</div>

			<p>
			The previous lesson showed 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 {@link android.app.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
			{@link java.util.concurrent.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.
			</p>
			<p>
			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
			<code>synchronized</code> 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
			<a href="{@docRoot}http://developer.android.com/guide/components/processes-and-threads.html">
			Processes and Threads</a> API guide.

			</p>
			<h2 id="ClassStructure">Define the Thread Pool Class</h2>
			<p>
			Instantiate {@link java.util.concurrent.ThreadPoolExecutor} in its own class. Within this class,
			do the following:
			</p>
			<dl>
			<dt>
			Use static variables for thread pools
			</dt>
			<dd>
			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
			{@link java.lang.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:
			<pre>
			public class PhotoManager {
			...
			static {
			...
			// Creates a single static instance of PhotoManager
			sInstance = new PhotoManager();
			}
			...
			</pre>
			</dd>
			<dt>
			Use a private constructor
			</dt>
			<dd>
			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 <code>synchronized</code> block:
			<pre>
			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() {
			...
			}
			</pre>
			</dd>
			<dt>
			Start your tasks by calling methods in the thread pool class.
			</dt>
			<dd>
			Define a method in the thread pool class that adds a task to a thread pool's queue. For
			example:
			<pre>
			public class PhotoManager {
			...
			// Called by the PhotoView to get a photo
			static public PhotoTask startDownload(
			PhotoView imageView,
			boolean cacheFlag) {
			...
			// Adds a download task to the thread pool for execution
			sInstance.
			mDownloadThreadPool.
			execute(downloadTask.getHTTPDownloadRunnable());
			...
			}
			</pre>
			</dd>
			<dt>
			Instantiate a {@link android.os.Handler} in the constructor and attach it to your app's
			UI thread.
			</dt>
			<dd>
			A {@link android.os.Handler} allows your app to safely call the methods of UI objects
			such as {@link android.view.View} objects. Most UI objects may only be safely altered from
			the UI thread. This approach is described in more detail in the lesson
			<a href="communicate-ui.html">Communicate with the UI Thread</a>. For example:
			<pre>
			private PhotoManager() {
			...
			// Defines a Handler object that's attached to the UI thread
			mHandler = 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) {
			...
			}
			...
			}
			}
			</pre>
			</dd>
			</dl>
			<h2 id="PoolParameters">Determine the Thread Pool Parameters</h2>
			<p>
			Once you have the overall class structure, you can start defining the thread pool. To
			instantiate a {@link java.util.concurrent.ThreadPoolExecutor} object, you need the
			following values:
			</p>
			<dl>
			<dt>
			Initial pool size and maximum pool size
			</dt>
			<dd>
			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:
			<pre>
			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();
			}
			</pre>
			This number may not reflect the number of physical cores in the device; some devices have
			CPUs that deactivate one or more cores depending on the system load. For these devices,
			{@link java.lang.Runtime#availableProcessors availableProcessors()} returns the number of
			<i>active</i> cores, which may be less than the total number of cores.
			</dd>
			<dt>
			Keep alive time and time unit
			</dt>
			<dd>
			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
			{@link java.util.concurrent.TimeUnit}.
			</dd>
			<dt>
			A queue of tasks
			</dt>
			<dd>
			The incoming queue from which {@link java.util.concurrent.ThreadPoolExecutor} takes
			{@link java.lang.Runnable} objects. To start code on a thread, a thread pool manager takes a
			{@link java.lang.Runnable} 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 the {@link java.util.concurrent.BlockingQueue} 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 for {@link java.util.concurrent.ThreadPoolExecutor}.
			This example uses the {@link java.util.concurrent.LinkedBlockingQueue} class:
			<pre>
			public class PhotoManager {
			...
			private PhotoManager() {
			...
			// A queue of Runnables
			private final BlockingQueue<Runnable> mDecodeWorkQueue;
			...
			// Instantiates the queue of Runnables as a LinkedBlockingQueue
			mDecodeWorkQueue = new LinkedBlockingQueue<Runnable>();
			...
			}
			...
			}
			</pre>
			</dd>
			</dl>
			<h2 id="ThreadPool">Create a Pool of Threads</h2>
			<p>
			To create a pool of threads, instantiate a thread pool manager by calling
			{@link java.util.concurrent.ThreadPoolExecutor#ThreadPoolExecutor ThreadPoolExecutor()}.
			This creates and manages a constrained group of threads. Because the initial pool size and
			the maximum pool size are the same, {@link java.util.concurrent.ThreadPoolExecutor} creates
			all of the thread objects when it is instantiated. For example:
			</p>
			<pre>
			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
			mDecodeThreadPool = new ThreadPoolExecutor(
			NUMBER_OF_CORES, // Initial pool size
			NUMBER_OF_CORES, // Max pool size
			KEEP_ALIVE_TIME,
			KEEP_ALIVE_TIME_UNIT,
			mDecodeWorkQueue);
			}
			</pre>

docs/html/training/multiple-threads/define-runnable.jd

0 → 100644

+110 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Specifying the Code to Run on a Thread

			trainingnavtop=true
			@jd:body

			<div id="tb-wrapper">
			<div id="tb">

			<!-- table of contents -->
			<h2>This lesson teaches you to</h2>
			<ol>
			<li><a href="#ExtendClass">Define a Class that Implements Runnable</a></li>
			<li><a href="#RunMethod">Implement the run() Method</a>
			</ol>

			<h2>You should also read</h2>
			<ul>
			<li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
			</ul>


			<h2>Try it out</h2>
			<div class="download-box">
			<a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
			<p class="filename">ThreadSample.zip</p>
			</div>
			</div>

			</div>
			</div>

			<p>
			This lesson shows you how to implement a {@link java.lang.Runnable} class, which runs the code
			in its {@link java.lang.Runnable#run Runnable.run()} method on a separate thread. You can also
			pass a {@link java.lang.Runnable} to another object that can then attach it to a thread and
			run it. One or more {@link java.lang.Runnable} objects that perform a particular operation are
			sometimes called a <i>task</i>.
			</p>
			<p>
			{@link java.lang.Thread} and {@link java.lang.Runnable} are basic classes that, on their own,
			have only limited power. Instead, they're the basis of powerful Android classes such as
			{@link android.os.HandlerThread}, {@link android.os.AsyncTask}, and
			{@link android.app.IntentService}. {@link java.lang.Thread} and {@link java.lang.Runnable} are
			also the basis of the class {@link java.util.concurrent.ThreadPoolExecutor}. This class
			automatically manages threads and task queues, and can even run multiple threads in parallel.
			</p>
			<h2 id="ExtendClass">Define a Class that Implements Runnable</h2>
			<p>
			Implementing a class that implements {@link java.lang.Runnable} is straightforward. For example:
			</p>
			<pre>
			public class PhotoDecodeRunnable implements Runnable {
			...
			@Override
			public void run() {
			/*
			* Code you want to run on the thread goes here
			*/
			...
			}
			...
			}
			</pre>
			<h2 id="RunMethod">Implement the run() Method</h2>
			<p>
			In the class, the {@link java.lang.Runnable#run Runnable.run()} method contains the
			code that's executed. Usually, anything is allowable in a {@link java.lang.Runnable}. Remember,
			though, that the {@link java.lang.Runnable} won't be running on the UI thread, so it can't
			directly modify UI objects such as {@link android.view.View} objects. To communicate with
			the UI thread, you have to use the techniques described in the lesson
			<a href="communicate-ui.html">Communicate with the UI Thread</a>.
			</p>
			<p>
			At the beginning of the {@link java.lang.Runnable#run run()} method, set the thread to use
			background priority by calling
			{@link android.os.Process#setThreadPriority Process.setThreadPriority()} with
			{@link android.os.Process#THREAD_PRIORITY_BACKGROUND}. This approach reduces
			resource competition between the {@link java.lang.Runnable} object's thread and the UI
			thread.
			</p>
			<p>
			You should also store a reference to the {@link java.lang.Runnable} object's
			{@link java.lang.Thread} in the {@link java.lang.Runnable} itself, by calling
			{@link java.lang.Thread#currentThread() Thread.currentThread()}.
			</p>
			<p>
			The following snippet shows how to set up the {@link java.lang.Runnable#run run()} method:
			</p>
			<pre>
			class PhotoDecodeRunnable implements Runnable {
			...
			/*
			* Defines the code to run for this task.
			*/
			@Override
			public void run() {
			// Moves the current Thread into the background
			android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_BACKGROUND);
			...
			/*
			* Stores the current Thread in the the PhotoTask instance,
			* so that the instance
			* can interrupt the Thread.
			*/
			mPhotoTask.setImageDecodeThread(Thread.currentThread());
			...
			}
			...
			}
			</pre>

docs/html/training/multiple-threads/index.jd

0 → 100644

+83 −0

File added.

Preview size limit exceeded, changes collapsed.

docs/html/training/multiple-threads/run-code.jd

0 → 100644

+148 −0

File added.

Preview size limit exceeded, changes collapsed.