⬆️ Improve result code from a Background Task

[timrijckaert]

Actually this was an idea we already discussed with @jeremie-movify and @petermnt before.
The return of a boolean as the result of a background job was a MVP approach and might be insufficient.

Ideally we would want to return some sort of enum representing the success state of a background task.

Android already expects either a:

• Result.failure()

  • Used to indicate that the work completed with a permanent failure. Any work that depends
    on this will also be marked as failed and will not be run. If you need child workers
    to run, you need to return Result.Success() failure indicates a permanent
    stoppage of the chain of work.

• Result.success()

  • Used to indicate that the work completed successfully. Any work that depends on this
    can be executed as long as all of its other dependencies and constraints are met.

• Result.Retry()

  • Used to indicate that the work encountered a transient failure and should be retried with
    backoff.

As of now (0.0.12) the plugin will map the returning bool as following:

• false -> Result.retry()
• true -> Result.success()

I thought the iOS return code was similarly mapped.

We could then have something like:

void callbackDispatcher() {
  var result = Result.retry
  Workmanager.executeTask((task) async {
    switch (task) {
      case simpleTaskKey:
       print("do some background work");
       result = Result.success
        break;
    }

    return Future.value(result);
  });
}

Originally posted by @timrijckaert in #20 (comment)

[petermnt]

1 problem we'll need to figure out is how we can map things together.

Android has failure, success, retry while iOS has newData, noData and failure.
They inherently have a different meaning.

The failure vs retry would not be able to be translated to the iOS return value, while newData vs noData would not be able to be translated to the Android return value.
That already means though that it's a bad idea to allow a user to return 'failure' instead of 'retry', because that would only imply 'don't retry' on Android, not on iOS.

some options I see:

• return a tuple of a CupertinoResult and AndroidResult
• stick with true/false to be able to consistently translate it to both platforms
• return noData, newData and failure which on android would map to success, success, retry

Another thing to keep in mind is what the options with the iOS 13 system are.

[timrijckaert]

Exactly we'll need to figure out how we will restructure the whole API to accommodate the changes for BGAppRefreshTask.

However I feel strongly to keep the Dart API simple; I think it's too much of a burden to let the user decide the different enum for each platform.
Ideally Dart will do the internal mapping to the correct native enum.
Finding a common ground will be difficult. 😀
So maybe returning a boolean is not so bad after all.

Could someone explain what newData, noData and failure mean on iOS?

[Kymer]

case newData
New data was successfully downloaded.
case noData
There was no new data to download.
case failed
An attempt to download data was made but that attempt failed.

An excerpt from the docs:

When a good opportunity arises, the system wakes or launches your app into the background and calls the app delegate’s application:performFetchWithCompletionHandler: method. Use that method to check for new content and initiate a download operation if content is available. As soon as you finish downloading the new content, you must execute the provided completion handler block, passing a result that indicates whether content was available. Executing this block tells the system that it can move your app back to the suspended state and evaluate its power usage. Apps that download small amounts of content quickly, and accurately reflect when they had content available to download, are more likely to receive execution time in the future than apps that take a long time to download their content or that claim content was available but then do not download anything.

So tl;dr: reporting an accurate UIBackgroundFetchResult will increase the chances of your app getting more opportunities to do background work in the future.

Not sure how the system asses the "accurateness" of the reported UIBackgroundFetchResult though... Dark black-box magic 🙃

[petermnt]

BgTask actually only support success/failure.
https://developer.apple.com/documentation/backgroundtasks/bgtask/3142236-settaskcompleted

It doesn't automatically reschedule though. So 1 way to model it that it's consistent between WorkManager and BgTask would be supporting an enum with values retry, failure, success.
For Android this could map to the return values.
For iOS it could map like this:

• success => setTaskCompleted(success: true)
• failure => setTaskCompleted(success: false)
• retry => setTaskCompleted(success: false) + reschedule

[timrijckaert]

So if I understand correctly iOS will not automagically reschedule when you return failure ?
Then what is this result code used for?

Is there a penalty from Apple if we were to do the retry this way?
Is there a canonical way from the docs on how to accomplish recurring tasks on iOS with this new API?

[Kymer]

No, that is the intended usage of the API. They even mention it in the docs:

setTaskCompleted(success:)
Informs the background task scheduler that the task is complete.

Discussion
Not calling setTaskCompleted(success:) before the time for the task expires may result in the system killing your app.
You can reschedule an unsuccessful required task. 👈

Scheduling is completely 'developer managed', so whatever makes sense for your use case. They showed an example of a "scheduleIfNeeded()" implementation in the WWDC19 session about the new API.

Here's a screengrab of the relevant part of the session Advances in App Background Execution, around 32:07 🕑:

[timrijckaert]

Ok, good to hear.
Still weird out by the way iOS constructs these dubious API's thought 🧐