Improve some docs, fix some debugging.

- Add docs to Binder, Messenger, ResultReceier to explain their
  relation (or lack there-of) to process lifecycle.
- Clarify some aspects of process lifecycle for services.
- Fix help text of am command.
- Fix per-package dumping of battery stats to not include history.
- Fix per-package dumping of proc stats to only include aggregated
  and current stats and fix some formatting.
- Fix per-process dumping of meminfo to have an option to interpret
  the input as a package, so including all processes that are
  running code of that package.
- Fix top-level per-package debug output to correctly include all
  of these improvements and give them a little more time (10s) to
  complete for timing out.

Change-Id: I2a04c0f862bd47b08329443d722345a13ad9b6e2

1 files changed, 11 insertions, 3 deletions

diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index ec9960d..c8e0031 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -192,7 +192,7 @@ import java.io.PrintWriter;
  * When running low on memory and needing to kill existing processes, the
  * priority of a process hosting the service will be the higher of the
  * following possibilities:
- * 
+ *
  * <ul>
  * <li><p>If the service is currently executing code in its
  * {@link #onCreate onCreate()}, {@link #onStartCommand onStartCommand()},
@@ -203,11 +203,19 @@ import java.io.PrintWriter;
  * to be less important than any processes that are currently visible to the
  * user on-screen, but more important than any process not visible.  Because
  * only a few processes are generally visible to the user, this means that
- * the service should not be killed except in extreme low memory conditions.
+ * the service should not be killed except in low memory conditions.  However, since
+ * the user is not directly aware of a background service, in that state it <em>is</em>
+ * considered a valid candidate to kill, and you should be prepared for this to
+ * happen.  In particular, long-running services will be increasingly likely to
+ * kill and are guaranteed to be killed (and restarted if appropriate) if they
+ * remain started long enough.
  * <li><p>If there are clients bound to the service, then the service's hosting
  * process is never less important than the most important client.  That is,
  * if one of its clients is visible to the user, then the service itself is
- * considered to be visible.
+ * considered to be visible.  The way a client's importance impacts the service's
+ * importance can be adjusted through {@link Context#BIND_ABOVE_CLIENT},
+ * {@link Context#BIND_ALLOW_OOM_MANAGEMENT}, {@link Context#BIND_WAIVE_PRIORITY},
+ * {@link Context#BIND_IMPORTANT}, and {@link Context#BIND_ADJUST_WITH_ACTIVITY}.
  * <li><p>A started service can use the {@link #startForeground(int, Notification)}
  * API to put the service in a foreground state, where the system considers
  * it to be something the user is actively aware of and thus not a candidate