diff options
Diffstat (limited to 'chromium/components/background_task_scheduler/README.md')
-rw-r--r-- | chromium/components/background_task_scheduler/README.md | 52 |
1 files changed, 35 insertions, 17 deletions
diff --git a/chromium/components/background_task_scheduler/README.md b/chromium/components/background_task_scheduler/README.md index c48720d51da..bc83b48d005 100644 --- a/chromium/components/background_task_scheduler/README.md +++ b/chromium/components/background_task_scheduler/README.md @@ -7,21 +7,39 @@ instead of using things like `IntentService` or polling using alarms. Using the system API is beneficial as it has a full view of what goes on in the system and can schedule jobs accordingly. -However, this functionality was introduced in Android L, and -the API has been very stable since Android M. This means that we also need a -similar framework for older versions of Android, which is provided by -Google Play services. We prefer system APIs, since they do not require including -external libraries which bloats the APK size of Chrome and adds unnecessary -complexity. The GcmNetworkManager is only used when the system API is not -available. - -The `background_task_scheduler` component provides a new framework for use -within chromium to schedule and execute background jobs using the frameworks -available on a given version of Android. -The public API of the framework is similar to that of the Android -`JobScheduler`, but it is backed by either the system `JobScheduler` API or by -GcmNetworkManager. What service is used to back the framework remains unknown to -callers of the API. +However, that leaves an API gap for Android L and below. Prior to Android L, the +`JobScheduler` API was not available at all. It was introduced in Android L; but +is not recommended on that platform, because it limits task execution time to 1 +minute. This is not really practically usable. For example, merely setting up a +network connection will often burn through much of that budget. Android M+ +extends this execution time limit to 10 minutes. + +For these older platforms, we can leverage the GcmNetworkManager API provided by +Google Play services to implement a suitable replacement for the JobScheduler +API. The `background_task_scheduler` component provides a new framework for use +within Chromium to schedule and execute background jobs using the frameworks +available on a given version of Android. The public API of the framework is +similar to that of the Android `JobScheduler`, but it is backed by either the +system `JobScheduler` API or by GcmNetworkManager. What service is used to back +the framework remains a black box to callers of the API. + +In practice, we prefer to use system APIs, since they do not require including +external libraries, which would bloat the APK size of Chrome and add unnecessary +complexity. Thus, the GcmNetworkManager is only used when the system API is not +available (or available but not considered stable enough). That is, the +JobScheduler API is used on Android M+; and the GcmNetworkManager is used +otherwise. + +> **WARNING: The GcmNetworkManager fallback is not yet implemented.** Please +> treat the above as a target state, and do not yet add any dependencies on the +> BackgroundTaskScheduler API that require pre-M compatibility. + +> NOTE: Even with the GcmNetworkManager fallback, there are devices that would +> remain unsupported, as not all devices have Google Play services +> available. Ultimately, this component hopes to provide a full compatibility +> layer on top of `JobScheduler`. However, until that is implemented, please be +> thoughtful about whether this component provides the coverage that your +> background task needs. ## What is a task @@ -95,14 +113,14 @@ When the task is ready for scheduling, you use the `BackgroundTaskScheduler` and use it to schedule the job. ```java -BackgroundTaskScheduleFactory.getScheduler().schedule(myTaskInfo); +BackgroundTaskSchedulerFactory.getScheduler().schedule(myTaskInfo); ``` If you ever need to cancel a task, you can do that by calling `cancel`, and passing in the task ID: ```java -BackgroundTaskScheduleFactory.getScheduler().cancel(TaskIds.YOUR_FEATURE); +BackgroundTaskSchedulerFactory.getScheduler().cancel(TaskIds.YOUR_FEATURE); ``` ## Passing task arguments |