Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ab4a81b3 authored by Dianne Hackborn's avatar Dianne Hackborn
Browse files

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
parent f9df9dd8

cmds/am/src/com/android/commands/am/Am.java

+3 −5
Original line number Diff line number Diff line
@@ -114,11 +114,7 @@ public class Am extends BaseCommand { 
                "       am broadcast [--user <USER_ID> | all | current] <INTENT>\n" +

                "       am instrument [-r] [-e <NAME> <VALUE>] [-p <FILE>] [-w]\n" +

                "               [--user <USER_ID> | current]\n" +

                "               [--no-window-animation]\n" +

                "               [--abi <ABI>]\n : Launch the instrumented process with the "  +

                "                   selected ABI. This assumes that the process supports the" +

                "                   selected ABI." +

                "               <COMPONENT>\n" +

                "               [--no-window-animation] [--abi <ABI>] <COMPONENT>\n" +

                "       am profile start [--user <USER_ID> current] <PROCESS> <FILE>\n" +

                "       am profile stop [--user <USER_ID> current] [<PROCESS>]\n" +

                "       am dumpheap [--user <USER_ID> current] [-n] <PROCESS> <FILE>\n" +
@@ -194,6 +190,8 @@ public class Am extends BaseCommand { 
                "    --user <USER_ID> | current: Specify user instrumentation runs in;\n" +

                "        current user if not specified.\n" +

                "    --no-window-animation: turn off window animations while running.\n" +

                "    --abi <ABI>: Launch the instrumented process with the selected ABI.\n"  +

                "        This assumes that the process supports the selected ABI.\n" +

                "\n" +

                "am profile: start and stop profiler on a process.  The given <PROCESS> argument\n" +

                "  may be either a process name or pid.  Options are:\n" +

core/java/android/app/ActivityManager.java

+5 −5
Original line number Diff line number Diff line
@@ -2621,17 +2621,17 @@ public class ActivityManager { 
    public static void dumpPackageStateStatic(FileDescriptor fd, String packageName) {

        FileOutputStream fout = new FileOutputStream(fd);

        PrintWriter pw = new FastPrintWriter(fout);

        dumpService(pw, fd, "package", new String[] { packageName });

        pw.println();

        dumpService(pw, fd, Context.ACTIVITY_SERVICE, new String[] {

                "-a", "package", packageName });

        pw.println();

        dumpService(pw, fd, "meminfo", new String[] { "--local", packageName });

        dumpService(pw, fd, "meminfo", new String[] { "--local", "--package", packageName });

        pw.println();

        dumpService(pw, fd, ProcessStats.SERVICE_NAME, new String[] { "-a", packageName });

        dumpService(pw, fd, ProcessStats.SERVICE_NAME, new String[] { packageName });

        pw.println();

        dumpService(pw, fd, "usagestats", new String[] { "--packages", packageName });

        pw.println();

        dumpService(pw, fd, "package", new String[] { packageName });

        pw.println();

        dumpService(pw, fd, BatteryStats.SERVICE_NAME, new String[] { packageName });

        pw.flush();

    }
@@ -2649,7 +2649,7 @@ public class ActivityManager { 
            tp = new TransferPipe();

            tp.setBufferPrefix("  ");

            service.dumpAsync(tp.getWriteFd().getFileDescriptor(), args);

            tp.go(fd);

            tp.go(fd, 10000);

        } catch (Throwable e) {

            if (tp != null) {

                tp.kill();

core/java/android/app/Service.java

+11 −3
Original line number Diff line number Diff line
@@ -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

core/java/android/os/Binder.java

+20 −3
Original line number Diff line number Diff line
@@ -31,7 +31,7 @@ import java.lang.reflect.Modifier; 
 * Base class for a remotable object, the core part of a lightweight

 * remote procedure call mechanism defined by {@link IBinder}.

 * This class is an implementation of IBinder that provides

 * the standard support creating a local implementation of such an object.

 * standard local implementation of such an object.

 *

 * <p>Most developers will not implement this class directly, instead using the

 * <a href="{@docRoot}guide/components/aidl.html">aidl</a> tool to describe the desired
@@ -40,6 +40,23 @@ import java.lang.reflect.Modifier; 
 * protocol or simply instantiate a raw Binder object directly to use as a

 * token that can be shared across processes.

 *

 * <p>This class is just a basic IPC primitive; it has no impact on an application's

 * lifecycle, and is valid only as long as the process that created it continues to run.

 * To use this correctly, you must be doing so within the context of a top-level

 * application component (a {@link android.app.Service}, {@link android.app.Activity},

 * or {@link android.content.ContentProvider}) that lets the system know your process

 * should remain running.</p>

 *

 * <p>You must keep in mind the situations in which your process

 * could go away, and thus require that you later re-create a new Binder and re-attach

 * it when the process starts again.  For example, if you are using this within an

 * {@link android.app.Activity}, your activity's process may be killed any time the

 * activity is not started; if the activity is later re-created you will need to

 * create a new Binder and hand it back to the correct place again; you need to be

 * aware that your process may be started for another reason (for example to receive

 * a broadcast) that will not involve re-creating the activity and thus run its code

 * to create a new Binder.</p>

 *

 * @see IBinder

 */

public class Binder implements IBinder {

core/java/android/os/Messenger.java

+7 −0
Original line number Diff line number Diff line
@@ -21,6 +21,13 @@ package android.os; 
 * This allows for the implementation of message-based communication across

 * processes, by creating a Messenger pointing to a Handler in one process,

 * and handing that Messenger to another process.

 *

 * <p>Note: the implementation underneath is just a simple wrapper around

 * a {@link Binder} that is used to perform the communication.  This means

 * semantically you should treat it as such: this class does not impact process

 * lifecycle management (you must be using some higher-level component to tell

 * the system that your process needs to continue running), the connection will

 * break if your process goes away for any reason, etc.</p>

 */

public final class Messenger implements Parcelable {

    private final IMessenger mTarget;