diff options
Diffstat (limited to 'docs/html/guide/topics/fundamentals')
| -rw-r--r-- | docs/html/guide/topics/fundamentals/index.jd | 496 | ||||
| -rw-r--r-- | docs/html/guide/topics/fundamentals/processes-and-threads.jd | 425 |
2 files changed, 921 insertions, 0 deletions
diff --git a/docs/html/guide/topics/fundamentals/index.jd b/docs/html/guide/topics/fundamentals/index.jd new file mode 100644 index 0000000..de2e312 --- /dev/null +++ b/docs/html/guide/topics/fundamentals/index.jd @@ -0,0 +1,496 @@ +page.title=Application Fundamentals +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Quickview</h2> +<ul> + <li>Android applications are composed of one or more application components (activities, +services, content providers, and broadcast receivers)</li> + <li>Each component performs a different role in the overall application behavior, and each +one can be activated individually (even by other applications)</li> + <li>The manifest file must declare all components in the application and should also declare +all application requirements, such as the minimum version of Android required and any hardware +configurations required</li> + <li>Non-code application resources (images, strings, layout files, etc.) should include +alternatives for different device configurations (such as different strings for different +languages and different layouts for different screen sizes)</li> +</ul> + + +<h2>In this document</h2> +<ol> +<li><a href="#Components">Application Components</a> + <ol> + <li><a href="#ActivatingComponents">Activating components</a></li> + </ol> +</li> +<li><a href="#Manifest">The Manifest File</a> + <ol> + <li><a href="#DeclaringComponents">Declaring components</a></li> + <li><a href="#DeclaringRequirements">Declaring application requirements</a></li> + </ol> +</li> +<li><a href="#Resources">Application Resources</a></li> +</ol> +</div> +</div> + +<p>Android applications are written in the Java programming language. The Android SDK tools compile +the code—along with any data and resource files—into an <i>Android package</i>, an +archive file with an {@code .apk} suffix. All the code in a single {@code .apk} file is considered +to be one application and is the file that Android-powered devices use to install the +application.</p> + +<p>Once installed on a device, each Android application lives in its own security sandbox: </p> + +<ul> + <li>The Android operating system is a multi-user Linux system in which each application is a +different user.</li> + +<li>By default, the system assigns each application a unique Linux user ID (the ID is used only by +the system and is unknown to the application). The system sets permissions for all the files in an +application so that only the user ID assigned to that application can access them. </li> + +<li>Each process has its own virtual machine (VM), so an application's code runs in isolation from +other applications.</li> + +<li>By default, every application runs in its own Linux process. Android starts the process when any +of the application's components need to be executed, then shuts down the process when it's no longer +needed or when the system must recover memory for other applications.</li> +</ul> + +<p>In this way, the Android system implements the <em>principle of least privilege</em>. That is, +each application, by default, has access only to the components that it requires to do its work and +no more. This creates a very secure environment in which an application cannot access parts of +the system for which it is not given permission.</p> + +<p>However, there are ways for an application to share data with other applications and for an +application to access system services:</p> + +<ul> + <li>It's possible to arrange for two applications to share the same Linux user ID, in which case +they are able to access each other's files. To conserve system resources, applications with the +same user ID can also arrange to run in the same Linux process and share the same VM (the +applications must also be signed with the same certificate).</li> + <li>An application can request permission to access device data such as the user's +contacts, SMS messages, the mountable storage (SD card), camera, Bluetooth, and more. All +application permissions must be granted by the user at install time.</li> +</ul> + +<p>That covers the basics regarding how an Android application exists within the system. The rest of +this document introduces you to:</p> +<ul> + <li>The core framework components that define your application.</li> + <li>The manifest file in which you declare components and required device features for your +application.</li> + <li>Resources that are separate from the application code and allow your application to +gracefully optimize its behavior for a variety of device configurations.</li> +</ul> + +<p class="note"><strong>Tip:</strong> If you're new to Android development, we suggest that you +follow the Beginner's Path link at the bottom of this page. For each document in the Application +Fundamentals, the Beginner's Path points you to the document we suggest you read next, in order +to get up to speed on the core Android concepts.</p> + + + +<h2 id="Components">Application Components</h2> + +<p>Application components are the essential building blocks of an Android application. Each +component is a different point through which the system can enter your application. Not all +components are actual entry points for the user and some depend on each other, but each one exists +as its own entity and plays a specific role—each one is a unique building block that +helps define your application's overall behavior.</p> + +<p>There are four different types of application components. Each type serves a distinct purpose +and has a distinct lifecycle that defines how the component is created and destroyed.</p> + +<p>Here are the four types of application components:</p> + +<dl> + +<dt><b>Activities</b></dt> + +<dd>An <i>activity</i> represents a single screen with a user interface. For example, +an email application might have one activity that shows a list of new +emails, another activity to compose an email, and another activity for reading emails. Although +the activities work together to form a cohesive user experience in the email application, each one +is independent of the others. As such, a different application can start any one of these +activities (if the email application allows it). For example, a camera application can start the +activity in the email application that composes new mail, in order for the user to share a picture. + +<p>An activity is implemented as a subclass of {@link android.app.Activity} and you can learn more +about it in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a> +developer guide.</p> +</dd> + + +<dt><b>Services</b></dt> + +<dd>A <i>service</i> is a component that runs in the background to perform long-running +operations or to perform work for remote processes. A service +does not provide a user interface. For example, a service might play music in the background while +the user is in a different application, or it might fetch data over the network without +blocking user interaction with an activity. Another component, such as an activity, can start the +service and let it run or bind to it in order to interact with it. + +<p>A service is implemented as a subclass of {@link android.app.Service} and you can learn more +about it in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer +guide.</p> +</dd> + + +<dt><b>Content providers</b></dt> + +<dd>A <i>content provider</i> manages a shared set of application data. You can store the data in +the file system, an SQLite database, on the web, or any other persistent storage location your +application can access. Through the content provider, other applications can query or even modify +the data (if the content provider allows it). For example, the Android system provides a content +provider that manages the user's contact information. As such, any application with the proper +permissions can query part of the content provider (such as {@link +android.provider.ContactsContract.Data}) to read and write information about a particular person. + +<p>Content providers are also useful for reading and writing data that is private to your +application and not shared. For example, the <a +href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application uses a +content provider to save notes.</p> + +<p>A content provider is implemented as a subclass of {@link android.content.ContentProvider} +and must implement a standard set of APIs that enable other applications to perform +transactions. For more information, see the <a +href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer +guide.</p> +</dd> + + +<dt><b>Broadcast receivers</b></dt> + +<dd>A <i>broadcast receiver</i> is a component that responds to system-wide broadcast +announcements. Many broadcasts originate from the system—for example, a broadcast announcing +that the screen has turned off, the battery is low, or a picture was captured. +Applications can also initiate broadcasts—for example, to let other applications know that +some data has been downloaded to the device and is available for them to use. Although broadcast +receivers don't display a user interface, they may <a +href="{@docRoot}guide/topics/ui/notifiers/notifications.html">create a status bar notification</a> +to alert the user when a broadcast event occurs. More commonly, though, a broadcast receiver is +just a "gateway" to other components and is intended to do a very minimal amount of work. For +instance, it might initiate a service to perform some work based on the event. + +<p>A broadcast receiver is implemented as a subclass of {@link android.content.BroadcastReceiver} +and each broadcast is delivered as an {@link android.content.Intent} object. For more information, +see the <a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> +developer guide.</p> +</dd> + +</dl> + + + +<p>A unique aspect of the Android system design is that any application can start another +application’s component. For example, if you want the user to capture a +photo with the device camera, there's probably another application that does that and your +application can use it, instead of developing an activity to capture a photo yourself. You don't +need to incorporate or even link to the code from the camera application. +Instead, you can simply start the activity in the camera application that captures a +photo. When complete, the photo is even returned to your application so you can use it. To the user, +it seems as if the camera is actually a part of your application.</p> + +<p>When the system starts a component, it starts the process for that application (if it's not +already running) and instantiates the classes needed for the component. For example, if your +application starts the activity in the camera application that captures a photo, that activity +runs in the process that belongs to the camera application, not in your application's process. +Therefore, unlike applications on most other systems, Android applications don't have a single entry +point (there's no {@code main()} function, for example).</p> + +<p>Because the system runs each application in a separate process with file permissions that +restrict access to other applications, your application cannot directly activate a component from +another application. The Android system, however, can. So, to activate a component in +another application, you must deliver a message to the system that specifies your <em>intent</em> to +start a particular component. The system then activates the component for you.</p> + + +<h3 id="ActivatingComponents">Activating Components</h3> + +<p>Three of the four component types—activities, services, and +broadcast receivers—are activated by an asynchronous message called an <em>intent</em>. +Intents bind individual components to each other at runtime (you can think of them +as the messengers that request an action from other components), whether the component belongs +to your application or another.</p> + +<p>An intent is defined by an {@link android.content.Intent} object, which defines a message to +activate either a specific component or a specific <em>type</em> of component—an intent +can be either explicit or implicit, respectively.</p> + +<p>For activities and services, an intent defines the action to perform (for example, to "view" or +"send" something) and may specify the URI of the data to act on (among other things that the +component being started might need to know). For example, an intent might convey a request for an +activity to present an image to the user or to open a web page. In some cases, you can start a +component in order to receive a result, in which case, the component that is started also returns +the result in an {@link android.content.Intent} object (for example, you can issue an intent to let +the user pick a personal contact and have it returned to you—the return intent includes a +URI pointing to the chosen contact). For broadcast receivers, the intent simply defines the +announcement being broadcast (for example, a broadcast to indicate the device battery is low +includes only a known action string that indicates "battery is low").</p> + +<p>The remaining type of component, content provider, is not activated by intents. Rather, it is +activated when targeted by a request from a {@link android.content.ContentResolver}. The content +resolver handles all direct transactions with the content provider so that the component that's +performing transactions with the provider doesn't need to and instead calls methods on the {@link +android.content.ContentResolver} object. This leaves a layer of abstraction between the content +provider and the component requesting information (for security).</p> + +<p>For more information about using intents, see the <a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and +Intent Filters</a> document. More information about activating specific components is also provided +in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>, <a +href="{@docRoot}guide/topics/fundamentals/services.html">Services</a>, and <a +href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer +guides.</p> + + +<h2 id="Manifest">The Manifest File</h2> + +<p>Before the Android system can start an application component, the system must know that the +component exists by reading the application's {@code AndroidManifest.xml} file (the "manifest" +file). Your application must declare all its components in this file, which must be at the root of +the application project directory.</p> + +<p>The manifest does a number of things in addition to declaring the application's components, +such as:</p> +<ul> + <li>Identify any user permissions the application requires, such as Internet access or +read-access to the user's contacts.</li> + <li>Declare the minimum <a href="{@docRoot}guide/appendix/api-levels.html">API Level</a> +required by the application, based on which APIs the application uses.</li> + <li>Declare hardware and software features used or required by the application, such as a camera, +bluetooth services, or a multitouch screen.</li> + <li>API libraries the application needs to be linked against (other than the Android framework +APIs), such as the <a +href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps +library</a>.</li> + <li>And more</li> +</ul> + + +<h3 id="DeclaringComponents">Declaring components</h3> + +<p>The primary task of the manifest is to inform the system about the application's components. For +example, a manifest file can declare an activity as follows: </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest ... > + <application android:icon="@drawable/app_icon.png" ... > + <activity android:name="com.example.project.ExampleActivity" + android:label="@string/example_label" ... > + </activity> + ... + </application> +</manifest></pre> + +<p>In the <code><a +href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +element, the {@code android:icon} attribute points to resources for an icon that identifies the +application.</p> + +<p>In the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element, +the {@code android:name} attribute specifies the fully qualified class name of the {@link +android.app.Activity} subclass and the {@code android:label} attributes specifies a string +to use as the user-visible label for the activity.</p> + +<p>You must declare all application components this way:</p> +<ul> + <li><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> elements +for activities</li> + <li><code><a +href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> elements for +services</li> + <li><code><a +href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> elements +for broadcast receivers</li> + <li><code><a +href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements +for content providers</li> +</ul> + +<p>Activities, services, and content providers that you include in your source but do not declare +in the manifest are not visible to the system and, consequently, can never run. However, +broadcast +receivers can be either declared in the manifest or created dynamically in code (as +{@link android.content.BroadcastReceiver} objects) and registered with the system by calling +{@link android.content.Context#registerReceiver registerReceiver()}.</p> + +<p>For more about how to structure the manifest file for your application, see the <a +href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a> +documentation. </p> + + + +<h3 id="DeclaringComponentCapabilities">Declaring component capabilities</h3> + +<p>As discussed above, in <a href="#ActivatingComponents">Activating Components</a>, you can use an +{@link android.content.Intent} to start activities, services, and broadcast receivers. You can do so +by explicitly naming the target component (using the component class name) in the intent. However, +the real power of intents lies in the concept of intent actions. With intent actions, you simply +describe the type of action you want to perform (and optionally, the data upon which you’d like to +perform the action) and allow the system to find a component on the device that can perform the +action and start it. If there are multiple components that can perform the action described by the +intent, then the user selects which one to use.</p> + +<p>The way the system identifies the components that can respond to an intent is by comparing the +intent received to the <i>intent filters</i> provided in the manifest file of other applications on +the device.</p> + +<p>When you declare a component in your application's manifest, you can optionally include +intent filters that declare the capabilities of the component so it can respond to intents +from other applications. You can declare an intent filter for your component by +adding an <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> element as a child of the component's declaration element.</p> + +<p>For example, an email application with an activity for composing a new email might declare an +intent filter in its manifest entry to respond to "send" intents (in order to send email). An +activity in your application can then create an intent with the “send” action ({@link +android.content.Intent#ACTION_SEND}), which the system matches to the email application’s “send” +activity and launches it when you invoke the intent with {@link android.app.Activity#startActivity +startActivity()}.</p> + +<p>For more about creating intent filters, see the <a +href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document. +</p> + + + +<h3 id="DeclaringRequirements">Declaring application requirements</h3> + +<p>There are a variety of devices powered by Android and not all of them provide the +same features and capabilities. In order to prevent your application from being installed on devices +that lack features needed by your application, it's important that you clearly define a profile for +the types of devices your application supports by declaring device and software requirements in your +manifest file. Most of these declarations are informational only and the system does not read +them, but external services such as Android Market do read them in order to provide filtering +for users when they search for applications from their device.</p> + +<p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a +href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as +requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an +Android version <em>lower</em> than 2.1 cannot install your application from Android Market.</p> + +<p>However, you can also declare that your applicaiton uses the camera, but does not +<em>require</em> it. In that case, your application must perform a check at runtime to determine +if the device has a camera and disable any features that use the camera if one is not available.</p> + +<p>Here are some of the important device characteristics that you should consider as you design and +develop your application:</p> + +<dl> + <dt>Screen size and density</dt> + <dd>In order to categorize devices by their screen type, Android defines two characteristics for +each device: screen size (the physical dimensions of the screen) and screen density (the physical +density of the pixels on the screen, or dpi—dots per inch). To simplify all the different +types of screen configurations, the Android system generalizes them into select groups that make +them easier to target. +<p>The screen sizes are: small, normal, large, and extra large.<br/> +The screen densities are: low density, medium density, high density, and extra high density.</p> + +<p>By default, your application is compatible with all screen sizes and densities, +because the Android system makes the appropriate adjustments to your UI layout and image +resources. However, you should create specialized layouts for certain screen sizes and provide +specialized images for certain densities, using alternative layout resources, and by declaring in +your manifest exactly which screen sizes your application supports with the <a +href="{@docRoot}guide/topics/manifest/supports-screens.html">{@code +<supports-screens>}</a> element.</p> +<p>For more information, see the <a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> +document.</p></dd> + + <dt>Input configurations</dt> + <dd>Many devices provide a different type of user input mechanism, such as a hardware keyboard, a +trackball, or a five-way navigation pad. If your application requires a particular kind of input +hardware, then you should declare it in your manifest with the <a +href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">{@code +<uses-configuration>}</a> element. However, it is rare that an application should require +a certain input configuration.</dd> + + <dt>Device features</dt> + <dd>There are many hardware and software features that may or may not exist on a given +Android-powered device, such as a camera, a light sensor, bluetooth, a certain +version of OpenGL, or the fidelity of the touchscreen. You should never assume that a certain +feature is available on all Android-powered devices (other than the availability of the standard +Android library), so you should declare any features used by your application with the <a +href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element.</dd> + + <dt>Platform Version</dt> + <dd>Different Android-powered devices often run different versions of the Android platform, +such as Android 1.6 or Android 2.3. Each successive version often includes additional APIs not +available in the previous version. In order to indicate which set of APIs are available, each +platform version specifies an <a +href="{@docRoot}guide/appendix/api-levels.html">API Level</a> (for example, Android 1.0 is API Level +1 and Android 2.3 is API Level 9). If you use any APIs that were added to the platform after +version 1.0, you should declare the minimum API Level in which those APIs were introduced using the +<a href="{@docRoot}guide/topics/manifest/uses-sdk.html">{@code <uses-sdk>}</a> element.</dd> +</dl> + +<p>It's important that you declare all such requirements for your application, because, when you +distribute your application on Android Market, Market uses these declarations to filter which +applications are available on each device. As such, your application should be available only to +devices that meet all your application requirements.</p> + +<p>For more information about how Android Market filters applications based on these (and other) +requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> +document.</p> + + + +<h2 id="Resources">Application Resources</h2> + +<p>An Android application is composed of more than just code—it requires resources that are +separate from the source code, such as images, audio files, and anything relating to the visual +presentation of the application. For example, you should define animations, menus, styles, colors, +and the layout of activity user interfaces with XML files. Using application resources makes it easy +to update various characteristics of your application without modifying code and—by providing +sets of alternative resources—enables you to optimize your application for a variety of +device configurations (such as different languages and screen sizes).</p> + +<p>For every resource that you include in your Android project, the SDK build tools define a unique +integer ID, which you can use to reference the resource from your application code or from +other resources defined in XML. For example, if your application contains an image file named {@code +logo.png} (saved in the {@code res/drawable/} directory), the SDK tools generate a resource ID +named {@code R.drawable.logo}, which you can use to reference the image and insert it in your +user interface.</p> + +<p>One of the most important aspects of providing resources separate from your source code +is the ability for you to provide alternative resources for different device +configurations. For example, by defining UI strings in XML, you can translate the strings into other +languages and save those strings in separate files. Then, based on a language <em>qualifier</em> +that you append to the resource directory's name (such as {@code res/values-fr/} for French string +values) and the user's language setting, the Android system applies the appropriate language strings +to your UI.</p> + +<p>Android supports many different <em>qualifiers</em> for your alternative resources. The +qualifier is a short string that you include in the name of your resource directories in order to +define the device configuration for which those resources should be used. As another +example, you should often create different layouts for your activities, depending on the +device's screen orientation and size. For example, when the device screen is in portrait +orientation (tall), you might want a layout with buttons to be vertical, but when the screen is in +landscape orientation (wide), the buttons should be aligned horizontally. To change the layout +depending on the orientation, you can define two different layouts and apply the appropriate +qualifier to each layout's directory name. Then, the system automatically applies the appropriate +layout depending on the current device orientation.</p> + +<p>For more about the different kinds of resources you can include in your application and how +to create alternative resources for various device configurations, see the <a +href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p> + + +<h2>Beginner's Path</h2> + +<p>For a close look at implementing activities—the components your users use to +interact with your application—continue with the <b><a +href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a></b> document.</p> + diff --git a/docs/html/guide/topics/fundamentals/processes-and-threads.jd b/docs/html/guide/topics/fundamentals/processes-and-threads.jd new file mode 100644 index 0000000..c35108e --- /dev/null +++ b/docs/html/guide/topics/fundamentals/processes-and-threads.jd @@ -0,0 +1,425 @@ +page.title=Processes and Threads +parent.title=Application Fundamentals +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>Every application runs in its own process and all components of the application run in that +process, by default</li> + <li>Any slow, blocking operations in an activity should be done in a new thread, to avoid slowing +down the user interface</li> +</ul> + +<h2>In this document</h2> +<ol> +<li><a href="#Processes">Processes</a> + <ol> + <li><a href="#Lifecycle">Process lifecycle</a></li> + </ol> +</li> +<li><a href="#Threads">Threads</a> + <ol> + <li><a href="#WorkerThreads">Worker threads</a></li> + <li><a href="#ThreadSafe">Thread-safe methods</a></li> + </ol> +</li> +<li><a href="#IPC">Interprocess Communication</a></li> +</ol> + +</div> +</div> + +<p>When an application component starts and the application does not have any other components +running, the Android system starts a new Linux process for the application with a single thread of +execution. By default, all components of the same application run in the same process and thread +(called the "main" thread). If an application component starts and there already exists a process +for that application (because another component from the application exists), then the component is +started within that process and uses the same thread of execution. However, you can arrange for +different components in your application to run in separate processes, and you can create additional +threads for any process.</p> + +<p>This document discusses how processes and threads work in an Android application.</p> + + +<h2 id="Processes">Processes</h2> + +<p>By default, all components of the same application run in the same process and most applications +should not change this. However, if you find that you need to control which process a certain +component belongs to, you can do so in the manifest file.</p> + +<p>The manifest entry for each type of component element—<a +href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>, <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code +<service>}</a>, <a href="{@docRoot}guide/topics/manifest/receiver-element.html">{@code +<receiver>}</a>, and <a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code +<provider>}</a>—supports an {@code android:process} attribute that can specify a +process in which that component should run. You can set this attribute so that each component runs +in its own process or so that some components share a process while others do not. You can also set +{@code android:process} so that components of different applications run in the same +process—provided that the applications share the same Linux user ID and are signed with the +same certificates.</p> + +<p>The <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> element also supports an {@code android:process} attribute, to set a +default value that applies to all components.</p> + +<p>Android might decide to shut down a process at some point, when memory is low and required by +other processes that are more immediately serving the user. Application +components running in the process that's killed are consequently destroyed. A process is started +again for those components when there's again work for them to do.</p> + +<p>When deciding which processes to kill, the Android system weighs their relative importance to +the user. For example, it more readily shuts down a process hosting activities that are no longer +visible on screen, compared to a process hosting visible activities. The decision whether to +terminate a process, therefore, depends on the state of the components running in that process. The +rules used to decide which processes to terminate is discussed below. </p> + + +<h3 id="Lifecycle">Process lifecycle</h3> + +<p>The Android system tries to maintain an application process for as long as possible, but +eventually needs to remove old processes to reclaim memory for new or more important processes. To +determine which processes to keep +and which to kill, the system places each process into an "importance hierarchy" based on the +components running in the process and the state of those components. Processes with the lowest +importance are eliminated first, then those with the next lowest importance, and so on, as necessary +to recover system resources.</p> + +<p>There are five levels in the importance hierarchy. The following list presents the different +types of processes in order of importance (the first process is <em>most important</em> and is +<em>killed last</em>):</p> + +<ol> + <li><b>Foreground process</b> + <p>A process that is required for what the user is currently doing. A + process is considered to be in the foreground if any of the following conditions are true:</p> + + <ul> + <li>It hosts an {@link android.app.Activity} that the user is interacting with (the {@link +android.app.Activity}'s {@link android.app.Activity#onResume onResume()} method has been +called).</li> + + <li>It hosts a {@link android.app.Service} that's bound to the activity that the user is +interacting with.</li> + + <li>It hosts a {@link android.app.Service} that's running "in the foreground"—the +service has called {@link android.app.Service#startForeground startForeground()}. + + <li>It hosts a {@link android.app.Service} that's executing one of its lifecycle +callbacks ({@link android.app.Service#onCreate onCreate()}, {@link android.app.Service#onStart +onStart()}, or {@link android.app.Service#onDestroy onDestroy()}).</li> + + <li>It hosts a {@link android.content.BroadcastReceiver} that's executing its {@link + android.content.BroadcastReceiver#onReceive onReceive()} method.</li> + </ul> + + <p>Generally, only a few foreground processes exist at any given time. They are killed only as +a last resort—if memory is so low that they cannot all continue to run. Generally, at that +point, the device has reached a memory paging state, so killing some foreground processes is +required to keep the user interface responsive.</p></li> + + <li><b>Visible process</b> + <p>A process that doesn't have any foreground components, but still can + affect what the user sees on screen. A process is considered to be visible if either of the + following conditions are true:</p> + + <ul> + <li>It hosts an {@link android.app.Activity} that is not in the foreground, but is still +visible to the user (its {@link android.app.Activity#onPause onPause()} method has been called). +This might occur, for example, if the foreground activity started a dialog, which allows the +previous activity to be seen behind it.</li> + + <li>It hosts a {@link android.app.Service} that's bound to a visible (or foreground) +activity.</li> + </ul> + + <p>A visible process is considered extremely important and will not be killed unless doing so +is required to keep all foreground processes running. </p> + </li> + + <li><b>Service process</b> + <p>A process that is running a service that has been started with the {@link +android.content.Context#startService startService()} method and does not fall into either of the two +higher categories. Although service processes are not directly tied to anything the user sees, they +are generally doing things that the user cares about (such as playing music in the background or +downloading data on the network), so the system keeps them running unless there's not enough memory +to retain them along with all foreground and visible processes. </p> + </li> + + <li><b>Background process</b> + <p>A process holding an activity that's not currently visible to the user (the activity's +{@link android.app.Activity#onStop onStop()} method has been called). These processes have no direct +impact on the user experience, and the system can kill them at any time to reclaim memory for a +foreground, +visible, or service process. Usually there are many background processes running, so they are kept +in an LRU (least recently used) list to ensure that the process with the activity that was most +recently seen by the user is the last to be killed. If an activity implements its lifecycle methods +correctly, and saves its current state, killing its process will not have a visible effect on +the user experience, because when the user navigates back to the activity, the activity restores +all of its visible state. See the <a +href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">Activities</a> +document for information about saving and restoring state.</p> + </li> + + <li><b>Empty process</b> + <p>A process that doesn't hold any active application components. The only reason to keep this +kind of process alive is for caching purposes, to improve startup time the next time a component +needs to run in it. The system often kills these processes in order to balance overall system +resources between process caches and the underlying kernel caches.</p> + </li> +</ol> + + + <p>Android ranks a process at the highest level it can, based upon the importance of the +components currently active in the process. For example, if a process hosts a service and a visible +activity, the process is ranked as a visible process, not a service process.</p> + + <p>In addition, a process's ranking might be increased because other processes are dependent on +it—a process that is serving another process can never be ranked lower than the process it is +serving. For example, if a content provider in process A is serving a client in process B, or if a +service in process A is bound to a component in process B, process A is always considered at least +as important as process B.</p> + + <p>Because a process running a service is ranked higher than a process with background activities, +an activity that initiates a long-running operation might do well to start a <a +href="{@docRoot}guide/topics/fundamentals/services.html">service</a> for that operation, rather than +simply create a worker thread—particularly if the operation will likely outlast the activity. +For example, an activity that's uploading a picture to a web site should start a service to perform +the upload so that the upload can continue in the background even if the user leaves the activity. +Using a service guarantees that the operation will have at least "service process" priority, +regardless of what happens to the activity. This is the same reason that broadcast receivers should +employ services rather than simply put time-consuming operations in a thread.</p> + + + + +<h2 id="Threads">Threads</h2> + +<p>When an application is launched, the system creates a thread of execution for the application, +called "main." This thread is very important because it is in charge of dispatching events to +the appropriate user interface widgets, including drawing events. It is also the thread in which +your application interacts with components from the Android UI toolkit (components from the {@link +android.widget} and {@link android.view} packages). As such, the main thread is also sometimes +called the UI thread.</p> + +<p>The system does <em>not</em> create a separate thread for each instance of a component. All +components that run in the same process are instantiated in the UI thread, and system calls to +each component are dispatched from that thread. Consequently, methods that respond to system +callbacks (such as {@link android.view.View#onKeyDown onKeyDown()} to report user actions +or a lifecycle callback method) always run in the UI thread of the process.</p> + +<p>For instance, when the user touches a button on the screen, your app's UI thread dispatches the +touch event to the widget, which in turn sets its pressed state and posts an invalidate request to +the event queue. The UI thread dequeues the request and notifies the widget that it should redraw +itself.</p> + +<p>When your app performs intensive work in response to user interaction, this single thread model +can yield poor performance unless you implement your application properly. Specifically, if +everything is happening in the UI thread, performing long operations such as network access or +database queries will block the whole UI. When the thread is blocked, no events can be dispatched, +including drawing events. From the user's perspective, the +application appears to hang. Even worse, if the UI thread is blocked for more than a few seconds +(about 5 seconds currently) the user is presented with the infamous "<a +href="http://developer.android.com/guide/practices/design/responsiveness.html">application not +responding</a>" (ANR) dialog. The user might then decide to quit your application and uninstall it +if they are unhappy.</p> + +<p>Additionally, the Andoid UI toolkit is <em>not</em> thread-safe. So, you must not manipulate +your UI from a worker thread—you must do all manipulation to your user interface from the UI +thread. Thus, there are simply two rules to Android's single thread model:</p> + +<ol> +<li>Do not block the UI thread +<li>Do not access the Android UI toolkit from outside the UI thread +</ol> + +<h3 id="WorkerThreads">Worker threads</h3> + +<p>Because of the single thread model described above, it's vital to the responsiveness of your +application's UI that you do not block the UI thread. If you have operations to perform +that are not instantaneous, you should make sure to do them in separate threads ("background" or +"worker" threads).</p> + +<p>For example, below is some code for a click listener that downloads an image from a separate +thread and displays it in an {@link android.widget.ImageView}:</p> + +<pre> +public void onClick(View v) { + new Thread(new Runnable() { + public void run() { + Bitmap b = loadImageFromNetwork("http://example.com/image.png"); + mImageView.setImageBitmap(b); + } + }).start(); +} +</pre> + +<p>At first, this seems to work fine, because it creates a new thread to handle the network +operation. However, it violates the second rule of the single-threaded model: <em>do not access the +Android UI toolkit from outside the UI thread</em>—this sample modifies the {@link +android.widget.ImageView} from the worker thread instead of the UI thread. This can result in +undefined and unexpected behavior, which can be difficult and time-consuming to track down.</p> + +<p>To fix this problem, Android offers several ways to access the UI thread from other +threads. Here is a list of methods that can help:</p> + +<ul> +<li>{@link android.app.Activity#runOnUiThread(java.lang.Runnable) +Activity.runOnUiThread(Runnable)}</li> +<li>{@link android.view.View#post(java.lang.Runnable) View.post(Runnable)}</li> +<li>{@link android.view.View#postDelayed(java.lang.Runnable, long) View.postDelayed(Runnable, +long)}</li> +</ul> + +<p>For example, you can fix the above code by using the {@link +android.view.View#post(java.lang.Runnable) View.post(Runnable)} method:</p> + +<pre> +public void onClick(View v) { + new Thread(new Runnable() { + public void run() { + final Bitmap bitmap = loadImageFromNetwork("http://example.com/image.png"); + mImageView.post(new Runnable() { + public void run() { + mImageView.setImageBitmap(bitmap); + } + }); + } + }).start(); +} +</pre> + +<p>Now this implementation is thread-safe: the network operation is done from a separate thread +while the {@link android.widget.ImageView} is manipulated from the UI thread.</p> + +<p>However, as the complexity of the operation grows, this kind of code can get complicated and +difficult to maintain. To handle more complex interactions with a worker thread, you might consider +using a {@link android.os.Handler} in your worker thread, to process messages delivered from the UI +thread. Perhaps the best solution, though, is to extend the {@link android.os.AsyncTask} class, +which simplifies the execution of worker thread tasks that need to interact with the UI.</p> + + +<h4 id="AsyncTask">Using AsyncTask</h4> + +<p>{@link android.os.AsyncTask} allows you to perform asynchronous work on your user +interface. It performs the blocking operations in a worker thread and then publishes the results on +the UI thread, without requiring you to handle threads and/or handlers yourself.</p> + +<p>To use it, you must subclass {@link android.os.AsyncTask} and implement the {@link +android.os.AsyncTask#doInBackground doInBackground()} callback method, which runs in a pool of +background threads. To update your UI, you should implement {@link +android.os.AsyncTask#onPostExecute onPostExecute()}, which delivers the result from {@link +android.os.AsyncTask#doInBackground doInBackground()} and runs in the UI thread, so you can safely +update your UI. You can then run the task by calling {@link android.os.AsyncTask#execute execute()} +from the UI thread.</p> + +<p>For example, you can implement the previous example using {@link android.os.AsyncTask} this +way:</p> + +<pre> +public void onClick(View v) { + new DownloadImageTask().execute("http://example.com/image.png"); +} + +private class DownloadImageTask extends AsyncTask<String, Void, Bitmap> { + /** The system calls this to perform work in a worker thread and + * delivers it the parameters given to AsyncTask.execute() */ + protected Bitmap doInBackground(String... urls) { + return loadImageFromNetwork(urls[0]); + } + + /** The system calls this to perform work in the UI thread and delivers + * the result from doInBackground() */ + protected void onPostExecute(Bitmap result) { + mImageView.setImageBitmap(result); + } +} +</pre> + +<p>Now the UI is safe and the code is simpler, because it separates the work into the +part that should be done on a worker thread and the part that should be done on the UI thread.</p> + +<p>You should read the {@link android.os.AsyncTask} reference for a full understanding on +how to use this class, but here is a quick overview of how it works:</p> + +<ul> +<li>You can specify the type of the parameters, the progress values, and the final +value of the task, using generics</li> +<li>The method {@link android.os.AsyncTask#doInBackground doInBackground()} executes automatically +on a worker thread</li> +<li>{@link android.os.AsyncTask#onPreExecute onPreExecute()}, {@link +android.os.AsyncTask#onPostExecute onPostExecute()}, and {@link +android.os.AsyncTask#onProgressUpdate onProgressUpdate()} are all invoked on the UI thread</li> +<li>The value returned by {@link android.os.AsyncTask#doInBackground doInBackground()} is sent to +{@link android.os.AsyncTask#onPostExecute onPostExecute()}</li> +<li>You can call {@link android.os.AsyncTask#publishProgress publishProgress()} at anytime in {@link +android.os.AsyncTask#doInBackground doInBackground()} to execute {@link +android.os.AsyncTask#onProgressUpdate onProgressUpdate()} on the UI thread</li> +<li>You can cancel the task at any time, from any thread</li> +</ul> + +<p class="caution"><strong>Caution:</strong> Another problem you might encounter when using a worker +thread is unexpected restarts in your activity due to a <a +href="{@docRoot}guide/topics/resources/runtime-changes.html">runtime configuration change</a> +(such as when the user changes the screen orientation), which may destroy your worker thread. To +see how you can persist your task during one of these restarts and how to properly cancel the task +when the activity is destroyed, see the source code for the <a +href="http://code.google.com/p/shelves/">Shelves</a> sample application.</p> + + +<h3 id="ThreadSafe">Thread-safe methods</h3> + +<p> In some situations, the methods you implement might be called from more than one thread, and +therefore must be written to be thread-safe. </p> + +<p>This is primarily true for methods that can be called remotely—such as methods in a <a +href="{@docRoot}guide/topics/fundamentals/bound-services.html">bound service</a>. When a call on a +method implemented in an {@link android.os.IBinder} originates in the same process in which the +{@link android.os.IBinder IBinder} is running, the method is executed in the caller's thread. +However, when the call originates in another process, the method is executed in a thread chosen from +a pool of threads that the system maintains in the same process as the {@link android.os.IBinder +IBinder} (it's not executed in the UI thread of the process). For example, whereas a service's +{@link android.app.Service#onBind onBind()} method would be called from the UI thread of the +service's process, methods implemented in the object that {@link android.app.Service#onBind +onBind()} returns (for example, a subclass that implements RPC methods) would be called from threads +in the pool. Because a service can have more than one client, more than one pool thread can engage +the same {@link android.os.IBinder IBinder} method at the same time. {@link android.os.IBinder +IBinder} methods must, therefore, be implemented to be thread-safe.</p> + +<p> Similarly, a content provider can receive data requests that originate in other processes. +Although the {@link android.content.ContentResolver} and {@link android.content.ContentProvider} +classes hide the details of how the interprocess communication is managed, {@link +android.content.ContentProvider} methods that respond to those requests—the methods {@link +android.content.ContentProvider#query query()}, {@link android.content.ContentProvider#insert +insert()}, {@link android.content.ContentProvider#delete delete()}, {@link +android.content.ContentProvider#update update()}, and {@link android.content.ContentProvider#getType +getType()}—are called from a pool of threads in the content provider's process, not the UI +thread for the process. Because these methods might be called from any number of threads at the +same time, they too must be implemented to be thread-safe. </p> + + +<h2 id="IPC">Interprocess Communication</h2> + +<p>Android offers a mechanism for interprocess communication (IPC) using remote procedure calls +(RPCs), in which a method is called by an activity or other application component, but executed +remotely (in another process), with any result returned back to the +caller. This entails decomposing a method call and its data to a level the operating system can +understand, transmitting it from the local process and address space to the remote process and +address space, then reassembling and reenacting the call there. Return values are then +transmitted in the opposite direction. Android provides all the code to perform these IPC +transactions, so you can focus on defining and implementing the RPC programming interface. </p> + +<p>To perform IPC, your application must bind to a service, using {@link +android.content.Context#bindService bindService()}. For more information, see the <a +href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer guide.</p> + + +<h2>Beginner's Path</h2> + +<p>For information about how to perform work in the background for an indefinite period of time +(without a user interface), continue with the <b><a +href="{@docRoot}guide/topics/fundamentals/services.html">Services</a></b> document.</p> + |