auto import from //depot/cupcake/@135843

1 files changed, 120 insertions, 0 deletions

diff --git a/docs/html/guide/topics/processes/process-lifecycle.jd b/docs/html/guide/topics/processes/process-lifecycle.jd
new file mode 100644
index 0000000..0380f94
--- /dev/null
+++ b/docs/html/guide/topics/processes/process-lifecycle.jd
@@ -0,0 +1,120 @@
+page.title=Processes and Application Life Cycle
+@jd:body
+
+<p>In most cases, every Android application runs in its own Linux process.
+This process is created for the application when some of its code needs to
+be run, and will remain running until it is no longer needed <em>and</em>
+the system needs to reclaim its memory for use by other applications.</p>
+
+<p>An unusual and fundamental feature of Android is that an application process's
+lifetime is <em>not</em> directly controlled by the application itself.
+Instead, it is determined by the system through a combination of the parts of the application
+that the system knows are running, how important these things are to the user,
+and how much overall memory is available in the system.</p>
+
+<p>It is important that
+application developers understand how different application components
+(in particular {@link android.app.Activity}, {@link android.app.Service},
+and {@link android.content.BroadcastReceiver}) impact the lifetime
+of the application's process.  <strong>Not using these components correctly can
+result in the system killing the application's process while it is doing
+important work.</strong></p>
+
+<p>A common example of a process life-cycle bug is a
+{@link android.content.BroadcastReceiver} that starts a thread when it
+receives an Intent in its {@link android.content.BroadcastReceiver#onReceive
+BroadcastReceiver.onReceive()}
+method, and then returns from the function.  Once it returns, the system
+considers the BroadcastReceiver to be no longer active, and thus, its hosting
+process no longer needed (unless other application components are active in
+it).  So, the system may kill the process at any time to reclaim memory, and in doing so,
+it terminates the spawned thread running in the process.  The solution to this problem
+is to start a {@link android.app.Service} from the BroadcastReceiver, so the
+system knows that there is still active work being done in the process.</p>
+
+<p>To determine which processes should be killed when low on memory, Android
+places each process into an "importance hierarchy" based on the components running in
+them and the state of those components. These process types are (in order of importance):</p>
+
+<ol>
+
+<li>A <strong>foreground process</strong> is one that is required for
+what the user is currently doing.  Various application components can
+cause its containing process to be considered foreground in different
+ways.  A process is considered to be in the foreground if any of the
+following conditions hold:
+ <ul>
+  <li> It is running an {@link android.app.Activity}
+  at the top of the screen that the user is interacting with (its
+  {@link android.app.Activity#onResume} method has been called).</li>
+  <li> It has a {@link android.content.BroadcastReceiver} that is currently running
+  (its {@link android.content.BroadcastReceiver#onReceive 
+  BroadcastReceiver.onReceive()} method is executing).</li>
+  <li>It has a {@link android.app.Service} that is currently executing code
+  in one of its callbacks ({@link android.app.Service#onCreate Service.onCreate()},
+  {@link android.app.Service#onStart Service.onStart()}, or
+  {@link android.app.Service#onDestroy Service.onDestroy()}).</li>
+ </ul>
+</li>
+<p>There will only ever be a few such processes in the system, and these will only
+be killed as a last resort if memory is so low that not even these processes
+can continue to run.  Generally, at this point, the device has
+reached a memory paging state, so this action is required in order to keep the user
+interface responsive.</p>
+</li>
+
+<li>A <strong>visible process</strong> is one holding an {@link android.app.Activity}
+that is visible to the user on-screen but not in the foreground (its
+{@link android.app.Activity#onPause} method has been called).  This may
+occur, for example, if the foreground Activity is displayed as a dialog
+that allows the previous Activity to be seen behind it.  Such a
+process is considered extremely important and will not be killed unless doing so is
+required to keep all foreground processes running.
+</li>
+
+<li>A <strong>service process</strong> is one holding a {@link android.app.Service}
+that has been started with the
+{@link android.content.Context#startService startService()} method.  Though these
+processes are not directly visible to the user, they are generally doing things
+that the user cares about (such as background mp3 playback or background
+network data upload or download), so the system will always keep such processes
+running unless there is not enough memory to retain all foreground and visible process.
+</li>
+
+<li>A <strong>background process</strong> is one holding an {@link android.app.Activity}
+that is not currently visible to the user  (its
+{@link android.app.Activity#onStop} method has been called).  These processes
+have no direct impact on the user experience.  Provided they implement
+their Activity life-cycle correctly
+(see {@link android.app.Activity} for more details), the system
+can kill such processes at any time to reclaim memory for one of the three
+previous processes types.  Usually there are many of these processes running,
+so they are kept in an LRU list to ensure the process that was most recently seen
+by the user is the last to be killed when running low on memory.
+</li>
+
+<li>An <strong>empty process</strong> is one that doesn't hold any active application
+components.  The only reason to keep such a process around is as a cache to
+improve startup time the next time a component of its application needs to
+run.  As such, the system will often kill these processes in order to
+balance overall system resources between these empty cached processes and the
+underlying kernel caches.
+</li>
+
+</ol>
+
+<p>When deciding how to classify a process, the system will base its decision on the most
+important level found among all the components currently active in the process.
+See the {@link android.app.Activity}, {@link android.app.Service}, and
+{@link android.content.BroadcastReceiver} documentation for more detail on how
+each of these components contribute to the overall life-cycle of a process.
+The documentation for each of these classes describes in more detail how
+they impact the overall life-cycle of their application.</p>
+
+<p>A process's priority may also be increased based on other dependencies
+a process has to it.  For example, if process A has bound to a
+{@link android.app.Service} with
+the {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE}
+flag or is using a
+{@link android.content.ContentProvider} in process B, then process B's
+classification will always be at least as important as process A's.</p>