diff options
author | Brad Fitzpatrick <bradfitz@android.com> | 2010-09-22 15:25:26 -0700 |
---|---|---|
committer | Android (Google) Code Review <android-gerrit@google.com> | 2010-09-22 15:25:26 -0700 |
commit | c87a8adc0e143e0c7efc62a1094ee6ac666e46d9 (patch) | |
tree | 29da38376967a19273dc082879c882461355bf83 | |
parent | 9d5fac517463526450268bf6353e32c13a8cdd0c (diff) | |
parent | 15ba4061116e088d62a7e05a0037f294f31dff06 (diff) | |
download | frameworks_base-c87a8adc0e143e0c7efc62a1094ee6ac666e46d9.zip frameworks_base-c87a8adc0e143e0c7efc62a1094ee6ac666e46d9.tar.gz frameworks_base-c87a8adc0e143e0c7efc62a1094ee6ac666e46d9.tar.bz2 |
Merge "Flesh out StrictMode docs." into gingerbread
-rw-r--r-- | core/java/android/os/StrictMode.java | 113 |
1 files changed, 98 insertions, 15 deletions
diff --git a/core/java/android/os/StrictMode.java b/core/java/android/os/StrictMode.java index f571c42..3ddaad9 100644 --- a/core/java/android/os/StrictMode.java +++ b/core/java/android/os/StrictMode.java @@ -30,8 +30,59 @@ import java.util.ArrayList; import java.util.HashMap; /** - * <p>StrictMode lets you impose stricter rules under which your - * application runs.</p> + * <p>StrictMode is a developer tool which lets you impose stricter + * rules under which your application runs. + * + * <p>StrictMode is most commonly used to catch accidental disk or + * network access on the application's main thread, where UI + * operations are received and animations take place. Keeping disk + * and network operations off the main thread makes for much smoother, + * more responsive applications. + * + * <p class="note">Note that even though an Android device's disk is + * often on flash memory, many devices run a filesystem on top of that + * memory with very limited concurrency. It's often the case that + * almost all disk accesses are fast, but may in individual cases be + * dramatically slower when certain I/O is happening in the background + * from other processes. If possible, it's best to assume that such + * things are not fast.</p> + * + * <p>Example code to enable from early in your + * {@link android.app.Application}, {@link android.app.Activity}, or + * other application component's + * {@link android.app.Application#onCreate} method: + * + * <pre> + * public void onCreate() { + * if (DEVELOPER_MODE) { + * StrictMode.setThreadPolicy(StrictMode.DISALLOW_DISK_WRITE | + * StrictMode.DISALLOW_DISK_READ | + * StrictMode.DISALLOW_NETWORK | + * StrictMode.PENALTY_LOG); + * } + * super.onCreate(); + * } + * </pre> + * + * <p>Then you can watch the output of <code>adb logcat</code> while you + * use your application. + * + * <p>If you find violations that you feel are problematic, there are + * a variety of tools to help solve them: threads, {@link android.os.Handler}, + * {@link android.os.AsyncTask}, {@link android.app.IntentService}, etc. + * But don't feel compelled to fix everything that StrictMode finds. In particular, + * a lot of disk accesses are often necessary during the normal activity lifecycle. Use + * StrictMode to find things you did on accident. Network requests on the UI thread + * are almost always a problem, though. + * + * <p class="note">StrictMode is not a security mechanism and is not + * guaranteed to find all disk or network accesses. While it does + * propagate its state across process boundaries when doing + * {@link android.os.Binder} calls, it's still ultimately a best + * effort mechanism. Notably, disk or network access from JNI calls + * won't necessarily trigger it. Future versions of Android may catch + * more (or fewer) operations, so you should never leave StrictMode + * enabled in shipping applications on the Android Market. */ public final class StrictMode { private static final String TAG = "StrictMode"; @@ -45,8 +96,22 @@ public final class StrictMode { private StrictMode() {} + /** + * Flag for {@link #setThreadPolicy} to signal that you don't intend for this + * thread to write to disk. + */ public static final int DISALLOW_DISK_WRITE = 0x01; + + /** + * Flag for {@link #setThreadPolicy} to signal that you don't intend for this + * thread to read from disk. + */ public static final int DISALLOW_DISK_READ = 0x02; + + /** + * Flag for {@link #setThreadPolicy} to signal that you don't intend for this + * thread to access the network. + */ public static final int DISALLOW_NETWORK = 0x04; /** @hide */ @@ -54,23 +119,30 @@ public final class StrictMode { DISALLOW_DISK_WRITE | DISALLOW_DISK_READ | DISALLOW_NETWORK; /** - * Flag to log to the system log. + * Penalty flag for {@link #setThreadPolicy} to log violations to + * the system log, visible with <code>adb logcat</code>. */ public static final int PENALTY_LOG = 0x10; // normal android.util.Log /** - * Show an annoying dialog to the user. Will be rate-limited to be only - * a little annoying. + * Penalty flag for {@link #setThreadPolicy} to show an annoying + * dialog to the developer, rate-limited to be only a little + * annoying. */ public static final int PENALTY_DIALOG = 0x20; /** - * Crash hard if policy is violated. + * Penalty flag for {@link #setThreadPolicy} to crash hard if + * policy is violated. */ public static final int PENALTY_DEATH = 0x40; /** - * Log a stacktrace to the DropBox on policy violation. + * Penalty flag for {@link #setThreadPolicy} to log a stacktrace + * and timing data to the + * {@link android.os.DropBoxManager DropBox} on policy violation. + * Intended mostly for platform integrators doing beta user field + * data collection. */ public static final int PENALTY_DROPBOX = 0x80; @@ -109,10 +181,17 @@ public final class StrictMode { }; /** - * Sets the policy for what actions the current thread is denied, - * as well as the penalty for violating the policy. + * Sets the policy for what actions the current thread isn't + * expected to do, as well as the penalty if it does. + * + * <p>Internally this sets a thread-local integer which is + * propagated across cross-process IPC calls, meaning you can + * catch violations when a system service or another process + * accesses the disk or network on your behalf. * - * @param policyMask a bitmask of DISALLOW_* and PENALTY_* values. + * @param policyMask a bitmask of DISALLOW_* and PENALTY_* values, + * e.g. {@link #DISALLOW_DISK_READ}, {@link #DISALLOW_DISK_WRITE}, + * {@link #DISALLOW_NETWORK}, {@link #PENALTY_LOG}. */ public static void setThreadPolicy(final int policyMask) { // In addition to the Java-level thread-local in Dalvik's @@ -160,7 +239,7 @@ public final class StrictMode { } /** - * Returns the bitmask of the current thread's blocking policy. + * Returns the bitmask of the current thread's policy. * * @return the bitmask of all the DISALLOW_* and PENALTY_* bits currently enabled */ @@ -169,8 +248,10 @@ public final class StrictMode { } /** - * Updates the current thread's policy mask to allow reading & - * writing to disk. + * A convenience wrapper around {@link #getThreadPolicy} and + * {@link #setThreadPolicy}. Updates the current thread's policy + * mask to allow both reading & writing to disk, returning the + * old policy so you can restore it at the end of a block. * * @return the old policy mask, to be passed to setThreadPolicy to * restore the policy. @@ -185,8 +266,10 @@ public final class StrictMode { } /** - * Updates the current thread's policy mask to allow reading from - * disk. + * A convenience wrapper around {@link #getThreadPolicy} and + * {@link #setThreadPolicy}. Updates the current thread's policy + * mask to allow reading from disk, returning the old + * policy so you can restore it at the end of a block. * * @return the old policy mask, to be passed to setThreadPolicy to * restore the policy. |