From 8cf3c1b53203a4d6802b67a43803f3e3ee6866b7 Mon Sep 17 00:00:00 2001 From: Eric Schmidt Date: Thu, 8 Sep 2016 14:17:11 -0700 Subject: [PATCH] docs: Update BroadcastReceiver docs for performance Bug: 30746266 Change-Id: I6d1537872918d955ab11d8596c6c96c64fe4f786 --- docs/html/guide/topics/manifest/receiver-element.jd | 14 ++++++++++++-- docs/html/training/articles/perf-anr.jd | 18 ++++++++++++++++++ .../monitoring-device-state/manifest-receivers.jd | 20 ++++++++++++++++---- 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd index 800ee8a6e4c7..c866047447e0 100644 --- a/docs/html/guide/topics/manifest/receiver-element.jd +++ b/docs/html/guide/topics/manifest/receiver-element.jd @@ -33,8 +33,18 @@ There are two ways to make a broadcast receiver known to the system: One is declare it in the manifest file with this element. The other is to create the receiver dynamically in code and register it with the {@link android.content.Context#registerReceiver Context.registerReceiver()} -method. See the {@link android.content.BroadcastReceiver} class description -for more on dynamically created receivers. +method. For more information about how to dynamically create receivers, see the +{@link android.content.BroadcastReceiver} class description. +

+ +

+ Warning: Limit how many broadcast + receivers you set in your app. Having too many broadcast receivers can + affect your app's performance and the battery life of users' devices. + For more information about APIs you can use instead of the + {@link android.content.BroadcastReceiver} class for scheduling background + work, see + Background Optimizations.

attributes:
diff --git a/docs/html/training/articles/perf-anr.jd b/docs/html/training/articles/perf-anr.jd index 88483545e2d9..faba95900829 100644 --- a/docs/html/training/articles/perf-anr.jd +++ b/docs/html/training/articles/perf-anr.jd @@ -14,6 +14,14 @@ page.article=true
  • Reinforcing Responsiveness
    • +

    You should also read

    + + @@ -165,6 +173,16 @@ application should start an {@link android.app.IntentService} if a potentially long running action needs to be taken in response to an intent broadcast.

    +

    + Another common issue with {@link android.content.BroadcastReceiver} objects + occurs when they execute too frequently. Frequent background execution can + reduce the amount of memory available to other apps. + For more information about how to enable and disable + {@link android.content.BroadcastReceiver} objects efficiently, see + Manipulating + Broadcast Receivers on Demand. +

    +

    Tip: You can use {@link android.os.StrictMode} to help find potentially long running operations such as network or database operations that diff --git a/docs/html/training/monitoring-device-state/manifest-receivers.jd b/docs/html/training/monitoring-device-state/manifest-receivers.jd index 3e36dba741a1..5efa2facf901 100644 --- a/docs/html/training/monitoring-device-state/manifest-receivers.jd +++ b/docs/html/training/monitoring-device-state/manifest-receivers.jd @@ -21,7 +21,10 @@ Efficiency

    You should also read

    @@ -32,13 +35,22 @@ android.content.BroadcastReceiver} for each state you're monitoring and register your application manifest. Then within each of these receivers you simply reschedule your recurring alarms based on the current device state.

    -

    A side-effect of this approach is that your app will wake the device each time any of these -receivers is triggered—potentially much more frequently than required.

    -

    A better approach is to disable or enable the broadcast receivers at runtime. That way you can use the receivers you declared in the manifest as passive alarms that are triggered by system events only when necessary.

    +

    + Warning: Limit how many broadcast + receivers you set in your app. Instead of using broadcast receivers, + consider using other APIs for + performing background work. For example, in Android 5.0 (API level 21) and + higher, you can use the {@link android.app.job.JobScheduler} class for + assigning work to be completed in the background. + For more information about APIs you can use instead of the + {@link android.content.BroadcastReceiver} class for scheduling background + work, see + Background Optimizations. +

    Toggle and Cascade State Change Receivers to Improve Efficiency

    -- 2.11.0