Merge "Update process importance documentation." into jb-dev
diff --git a/api/current.txt b/api/current.txt
index 2ddf096..46e3aa0 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -5713,7 +5713,7 @@
field public static final java.lang.String ACTION_USER_PRESENT = "android.intent.action.USER_PRESENT";
field public static final java.lang.String ACTION_VIEW = "android.intent.action.VIEW";
field public static final java.lang.String ACTION_VOICE_COMMAND = "android.intent.action.VOICE_COMMAND";
- field public static final java.lang.String ACTION_WALLPAPER_CHANGED = "android.intent.action.WALLPAPER_CHANGED";
+ field public static final deprecated java.lang.String ACTION_WALLPAPER_CHANGED = "android.intent.action.WALLPAPER_CHANGED";
field public static final java.lang.String ACTION_WEB_SEARCH = "android.intent.action.WEB_SEARCH";
field public static final java.lang.String CATEGORY_ALTERNATIVE = "android.intent.category.ALTERNATIVE";
field public static final java.lang.String CATEGORY_APP_BROWSER = "android.intent.category.APP_BROWSER";
diff --git a/core/java/android/app/ActivityManager.java b/core/java/android/app/ActivityManager.java
index 11b4c3a..7dce2d3 100644
--- a/core/java/android/app/ActivityManager.java
+++ b/core/java/android/app/ActivityManager.java
@@ -502,7 +502,16 @@
/**
* Return a list of the tasks that the user has recently launched, with
* the most recent being first and older ones after in order.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging and presenting
+ * task management user interfaces</b>. This should never be used for
+ * core logic in an application, such as deciding between different
+ * behaviors based on the information found here. Such uses are
+ * <em>not</em> supported, and will likely break in the future. For
+ * example, if multiple applications can be actively running at the
+ * same time, assumptions made about the meaning of the data here for
+ * purposes of control flow will be incorrect.</p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many tasks the
* user has started and the maximum number the system can remember.
@@ -669,6 +678,15 @@
* can be restarted in its previous state when next brought to the
* foreground.
*
+ * <p><b>Note: this method is only intended for debugging and presenting
+ * task management user interfaces</b>. This should never be used for
+ * core logic in an application, such as deciding between different
+ * behaviors based on the information found here. Such uses are
+ * <em>not</em> supported, and will likely break in the future. For
+ * example, if multiple applications can be actively running at the
+ * same time, assumptions made about the meaning of the data here for
+ * purposes of control flow will be incorrect.</p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many tasks the
* user has started.
@@ -1016,7 +1034,10 @@
/**
* Return a list of the services that are currently running.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or implementing
+ * service management type user interfaces.</b></p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many services
* are running.
@@ -1128,6 +1149,16 @@
}
}
+ /**
+ * Return general information about the memory state of the system. This
+ * can be used to help decide how to manage your own memory, though note
+ * that polling is not recommended and
+ * {@link android.content.ComponentCallbacks2#onTrimMemory(int)
+ * ComponentCallbacks2.onTrimMemory(int)} is the preferred way to do this.
+ * Also see {@link #getMyMemoryState} for how to retrieve the current trim
+ * level of your process as needed, which gives a better hint for how to
+ * manage its memory.
+ */
public void getMemoryInfo(MemoryInfo outInfo) {
try {
ActivityManagerNative.getDefault().getMemoryInfo(outInfo);
@@ -1497,6 +1528,9 @@
* Returns a list of application processes installed on external media
* that are running on the device.
*
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @return Returns a list of ApplicationInfo records, or null if none
* This list ordering is not specified.
* @hide
@@ -1511,7 +1545,10 @@
/**
* Returns a list of application processes that are running on the device.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @return Returns a list of RunningAppProcessInfo records, or null if there are no
* running processes (it will not return an empty list). This list ordering is not
* specified.
@@ -1544,7 +1581,10 @@
/**
* Return information about the memory usage of one or more processes.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @param pids The pids of the processes whose memory usage is to be
* retrieved.
* @return Returns an array of memory information, one for each
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index 6f19934..3824f44 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -637,6 +637,14 @@
* wallpaper it would like to use. This allows such applications to have
* a virtual wallpaper that is larger than the physical screen, matching
* the size of their workspace.
+ *
+ * <p>Note developers, who don't seem to be reading this. This is
+ * for <em>home screens</em> to tell what size wallpaper they would like.
+ * Nobody else should be calling this! Certainly not other non-home-screen
+ * apps that change the wallpaper. Those apps are supposed to
+ * <b>retrieve</b> the suggested size so they can construct a wallpaper
+ * that matches it.
+ *
* @param minimumWidth Desired minimum width
* @param minimumHeight Desired minimum height
*/
diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java
index 85294dd..a3b4e5e 100644
--- a/core/java/android/content/ComponentCallbacks2.java
+++ b/core/java/android/content/ComponentCallbacks2.java
@@ -88,7 +88,11 @@
* should never compare to exact values of the level, since new intermediate
* values may be added -- you will typically want to compare if the value
* is greater or equal to a level you are interested in.
- *
+ *
+ * <p>To retrieve the processes current trim level at any point, you can
+ * use {@link android.app.ActivityManager#getMyMemoryState
+ * ActivityManager.getMyMemoryState(RunningAppProcessInfo)}.
+ *
* @param level The context of the trim, giving a hint of the amount of
* trimming the application may like to perform. May be
* {@link #TRIM_MEMORY_COMPLETE}, {@link #TRIM_MEMORY_MODERATE},
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 6653336..d0d9bd6 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -1624,8 +1624,20 @@
/**
* Broadcast Action: The current system wallpaper has changed. See
* {@link android.app.WallpaperManager} for retrieving the new wallpaper.
+ * This should <em>only</em> be used to determine when the wallpaper
+ * has changed to show the new wallpaper to the user. You should certainly
+ * never, in response to this, change the wallpaper or other attributes of
+ * it such as the suggested size. That would be crazy, right? You'd cause
+ * all kinds of loops, especially if other apps are doing similar things,
+ * right? Of course. So please don't do this.
+ *
+ * @deprecated Modern applications should use
+ * {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WALLPAPER
+ * WindowManager.LayoutParams.FLAG_SHOW_WALLPAPER} to have the wallpaper
+ * shown behind their UI, rather than watching for this broadcast and
+ * rendering the wallpaper on their own.
*/
- @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
+ @Deprecated @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
public static final String ACTION_WALLPAPER_CHANGED = "android.intent.action.WALLPAPER_CHANGED";
/**
* Broadcast Action: The current device {@link android.content.res.Configuration}
diff --git a/docs/html/guide/topics/fundamentals/processes-and-threads.jd b/docs/html/guide/topics/fundamentals/processes-and-threads.jd
index 3d7710c..814d34e 100644
--- a/docs/html/guide/topics/fundamentals/processes-and-threads.jd
+++ b/docs/html/guide/topics/fundamentals/processes-and-threads.jd
@@ -30,11 +30,12 @@
</div>
</div>
-<p>When an application component starts and the application does not have any other components
+<p>When an application component starts and the process that should host that thread is not already
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
+for that application (because another component from the application exists or Android has been
+able to retain its previous process cached in the background), 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>
@@ -86,7 +87,10 @@
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
+<p>The exact mapping of processes to importance and the management of these processes is
+an implementation detail of the platform that changes over time. Broadly speaking, there
+are five levels in the current implementation that are of most relevance to application
+developers. The following list presents these different
types of processes in order of importance (the first process is <em>most important</em> and is
<em>killed last</em>):</p>
@@ -100,18 +104,15 @@
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>
+
+ <li>Another foreground process has a dependency on this one: either bound
+ to a Service in this process, or using a Content Provider of the process.</li>
</ul>
<p>Generally, only a few foreground processes exist at any given time. They are killed only as
@@ -130,43 +131,79 @@
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>
+ <li>Another visible process has a dependency on this one: either bound
+ to a Service in this process, or using a Content Provider of the process.</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>Perceptible process</b>
+ <p>A process that doesn't have any foreground or visible components, but is still
+ doing something that is directly perceptible by the user. A classic example of such
+ a process would be one doing background music playback. The main way applications
+ get into this state is through {@link android.app.Service#startForeground} or because
+ another perceptible process has a dependency on one of its services or content
+ providers. In addition, as of {@link android.os.Build.VERSION_CODES#HONEYCOMB},
+ processes can go into this state when {@link android.app.Activity#onStop
+ Activity.onStop()} is executing, allowing the process to continue executing
+ critical code after no longer being visible to the user but before going
+ fully into the background.</p>
+
+ <p>Like visible processes, a perceptible process is considered extremely important
+ and will not be killed unless doing so is required to keep all foreground and
+ visible 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
+android.content.Context#startService startService()} method and does not fall into any of the
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>
+are generally doing things that the user cares about (such as downloading a file the user has requested),
+so the system keeps them running unless there's not enough memory to retain them along with all
+foreground and visible processes. </p>
+
+ <p>Even though Android tries to keep these processes running, it is considered normal
+ operation for them to temporarily be killed to support the needs of more important
+ processes. For example, if the user opens a very heavy-weight web page that needs
+ most of the device's RAM, background services may be temporarily killed to satisfy
+ those needs. Services in these processes thus must be prepared to deal gracefully
+ with being killed while doing their work and later restarted.</p>
+
+ <p>In recent implementations of Android, there are actually a number of sub-divisions
+ in this area for processes that Android considers more important to the user and so
+ would like to try harder to keep around. For example, the process hosting the current
+ home app is generally kept in this area so that the user will not see long delays in
+ returning home because that process has been killed.</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
+ <li><b>Background (cached) process</b>
+ <p>The final importance level is for processes that are not of current significance.
+ This is basically any process that does not fall into one of the previous levels.
+ These processes have no direct impact on the user experience, and the system can kill
+ them at any time to reclaim memory for the other more important processes.
+ This includes everything from processes holding running activity objects that are not currently
+ visible to the user (the activity's {@link android.app.Activity#onStop onStop()}
+ method has been called) to processes that have no active code at all but may be
+ useful to keep around in case they are needed in the near future.</p>
+
+ <p>Usually there are many background processes being maintained, so they are kept
+ in an LRU list to allow older processes to be killed before more recent ones. This
+ helps reduce the frequency that new processes need to be creating, facilitating things
+ like more rapid switching between the applications the user has recently visited.
+ However, processes in this state must deal correctly with being killed and later
+ restarted when needed. For example, 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>
+ <p>Android may also employ other additional policies for killing background processes. For
+ example, there are typically restrictions on a maximum number of such processes to
+ keep around, and limits on the amount of time they can spend holding wake locks
+ or consuming CPU power until they will be removed.</p>
</li>
</ol>
@@ -176,23 +213,48 @@
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
+it—a process that is serving another process can not generally 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
+service in process A has been bound to by a client 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
+an activity that initiates a long-running operation may sometimes 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.
+simply create a worker thread—but only when the operation is a specific task that needs
+to be accomplished regardless of whether the user returns to the application.
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>
+regardless of what happens to the activity. This is not however an approach that should always
+be used. It would not be appropriate when simply downloading the data for a web page, since
+that can easily be restarted later if the user returns to the web browser. Allowing
+such a process to be in the background (instead of running a service) gives Android better
+information about how to manage that process in relation to others.
+ <p>For a similar reason, broadcast receivers will often employ services rather than
+ simply put time-consuming operations in a thread.</p>
+ <p>Some command line tools are available to help you understand how Android is managing
+ its processes. The most common command is <code>adb shell dumpsys activity</code>
+ which provides a summary of various key state, including at the end a list of the
+ process states, one per line (plus an optional second line for any key dependency
+ on that process), ordered from higher importance to lowest. The exact
+ contents of these lines has changed across different versions of Android, but the
+ typical state for one process in the list would be:</p>
+ <pre>
+Proc # 2: adj=prcp /F trm= 0 848:com.google.android.inputmethod.latin/u0a32 (service)
+ com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME<=Proc{417:system/1000}
+</pre>
+ <p>This is a perceptible process (adj=prcp) that is running with the foreground
+ scheduling class (/F), and has not recently been told to trim any memory
+ (trm= 0). Its process id is 848; its name is com.google.android.inputmethod.latin;
+ its Linux uid is u0a32 (10032), and the key state contributing to its current
+ importance level is a service.</p>
+
+ <p>The second line provides the name of the service that is important, because another
+ process has a dependency on it (here the system process).</p>
<h2 id="Threads">Threads</h2>