From 9c12816a62172d7d57e56ca239e1e95c21eac4ca Mon Sep 17 00:00:00 2001 From: David Friedman Date: Thu, 30 Jun 2016 17:23:29 -0700 Subject: [PATCH] Docs: Job-scheduling doc for new DAC Performance section. Change-Id: Iccdbfcede6774bd7b5e368c53637ca8e194c7ec5 --- docs/html/topic/performance/scheduling.jd | 285 ++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 docs/html/topic/performance/scheduling.jd diff --git a/docs/html/topic/performance/scheduling.jd b/docs/html/topic/performance/scheduling.jd new file mode 100644 index 000000000000..b6f0fdc1b230 --- /dev/null +++ b/docs/html/topic/performance/scheduling.jd @@ -0,0 +1,285 @@ +page.title=Intelligent Job-Scheduling +@jd:body + +
+ +
+ +

+Modern apps can perform many of their tasks asynchronously, outside the +direct flow of user interaction. Some examples of these asynchronous tasks are: +

+ + + +

+Scheduling this work intelligently can improve your app’s performance, +along with aspects of system health such as battery life. {@link android.app.job.JobScheduler} +does this scheduling work for you. +

+ +

+There are several APIs that your app can use to schedule background work. Chief +among these options is {@link android.app.job.JobScheduler}. +The {@link android.app.job.JobScheduler} API allows you to specify robust +conditions for executing tasks, +along with centralized task scheduling across the device for optimal +system health. {@link android.app.job.JobScheduler} also offers highly +scalable functionality: it is suitable for small tasks like clearing a cache, +and for large ones such as syncing a database to the cloud. +

+ +

+In addition to {@link android.app.job.JobScheduler}, there are several other +facilities available to help your app schedule work. These include: +

+ + + +

+This page provides brief introductions to {@link android.app.job.JobScheduler} +and other APIs that can help your app schedule work to maximize app performance +and system health. +

+ +

Android Framework JobScheduler

+ +

+{@link android.app.job.JobScheduler} is the Android framework’s native platform +for scheduling tasks or work. It first became available in Android 5.0 (API +level 21), and remains under active development. Notably, Android N (API +level 24) added the ability to trigger jobs based on +{@link android.content.ContentProvider} changes. +

+ +

+{@link android.app.job.JobScheduler} is implemented in the platform, which +allows it to collect information about jobs that need to run across all apps. +This information is used to schedule jobs to run at, or around, the same time. +Batching job execution in this fashion allows the device to enter and stay in +sleep states longer, preserving battery life. +

+ +

+You use {@link android.app.job.JobScheduler} by registering jobs, specifying +their requirements for network and timing. The system then gracefully schedules +the jobs to execute at the appropriate times. At the same time, it also defers +job execution as necessary to comply with + +Doze and App Standby restrictions. +{@link android.app.job.JobScheduler} provides many methods to define +job-execution conditions. +

+ +

+If your app targets Android 5.0 (API level 21), we recommend that you use the +{@link android.app.job.JobScheduler} to execute background tasks. For more +information about {@link android.app.job.JobScheduler}, see its +API-reference +documentation. +

+ +

AlarmManager

+ +

+The {@link android.app.AlarmManager} API is another option that the framework +provides for scheduling tasks. This API is useful in cases in which an app +needs to post a notification or set off an alarm at a very specific time. +

+ +

+You should only use this API for tasks that must execute at a specific time, +but do not require the other, more robust, execution conditions that +{@link android.app.job.JobScheduler} allows you to specify, such as device +idle and charging detect. +

+ +

+{@link android.app.AlarmManager} does not honor + +Doze and App Standby restrictions; it runs tasks even during + +Doze or App Standby mode. Additionally, +an app running during + +Doze or App Standby mode cannot use the network. +

+ +

Firebase JobDispatcher

+ +

+ +Firebase JobDispatcher is an open-source library that provides an API similar to +{@link android.app.job.JobScheduler} in the Android platform. + +Firebase JobDispatcher serves as a +{@link android.app.job.JobScheduler}-compatibility layer for apps targeting +versions of Android lower than 5.0 (API level 21). +

+ +

+ +Firebase JobDispatcher supports the use of Google Play services as an +implementation for dispatching (running) jobs, but the library also allows you +to define and use other implementations: For example, you might decide to use +{@link android.app.job.JobScheduler} or write your own, custom code. +Because of this versatility, we recommend that you use this + +Firebase JobDispatcher if your app targets a version of Android lower +than 5.0 (API level 21). +

+ +

+For more information about + +Firebase JobDispatcher, refer to its + +documentation and source code. +

+ +

GCM Network Manager

+ +

+GCM +Network Manager is a compatibility port of the Android +{@link android.app.job.JobScheduler} for apps that support versions of Android +prior to 5.0 (API level 21). This API has all of the same advantages as +{@link android.app.job.JobScheduler}. However, it depends on Google Play +services, which acts like {@link android.app.job.JobScheduler} by taking care +of cross-app job scheduling to improve battery life. This client library is +part of the Google Play services GCM client library, but does not require +that an app use +Google Cloud +Messaging. +

+ +

+This library is an earlier version of + +Firebase JobDispatcher. Forward development on GCM Network Manager has +stopped; we recommend that you use + +Firebase JobDispatcher going forward. +

+ +

Additional Facilities

+ +

+In addition to the APIs and libraries described above, there are also sync +adapters and services that can enable your app, under specific conditions, +to perform better and more robustly. +

+ +

SyncAdapter

+ +

+The framework continues to provide the +{@link android.content.AbstractThreadedSyncAdapter SyncAdapter} class for +managing tasks that sync data between the device and a server. Sync adapters are +designed specifically for syncing data between a device and the cloud; you +should only use them for this type of task. Sync adapters are more complex to +implement than the libraries and APIs mentioned above, because they require at +least a fake + +authenticatorand + +content provider implementation. For these reasons, you typically should +not create a sync adapter just to sync data to the cloud in the +background. Wherever possible, you should instead use +{@link android.app.job.JobScheduler}, + +Firebase JobDispatcher, or +GCM +Network Manager . +

+ +

+In Android N (API level 24), the {@code SyncManager} sits on top of +the {@link android.app.job.JobScheduler}. You should only use the +{@link android.content.AbstractThreadedSyncAdapter SyncAdapter} +class if you require the additional functionality that it provides. +

+ +

Services

+ +

+The Services +framework allows you to perform long-running operations in the background. +We recommend foreground services for tasks, such as playing +music, which need to stay resident for the user. Bound services also continue +to be useful for various use cases: for example, when a service needs to +run only when a user is viewing a fragment or activity. +

+ +

+You should avoid using started services that run perpetually or +perform periodic work, since they continue to use device resources +even when they are not performing useful tasks. Instead, you +should use other solutions that this page describes, +and that provide native lifecycle management. Use started services +only as a last resort. The Android platform may not support +started services in the future. +

+ +

Additional Points

+ +

+Regardless of the solution you adopt, keep the following points in mind: +

+ + -- 2.11.0