IssueTracker

There is an error in the following documentation:

http://developer.android.com/training/efficient-downloads/regular_updates.html

The first code snippet under "Optimize Polling with Inexact Repeating Alarms and Exponential Backoffs" is illustrating how to schedule an inexact timer for 1hr from now.

The code calculates the 'start' variable incorrectly however, because it returns the current system time in milliseconds since January 1, 1970 00:00:00 UTC rather than the Elapsed time (milliseconds since boot).

When using setInexactRepeating() API the triggerAtTime argument should be in the same timebase as the alarm (although the API doesn't check this). The code example will therefore set the alarm to fire years in the future, rather than in 1hour, because of the 40-odd year skew between the elapsed system time and realtime system time.

Instead the start variable should be set using the  SystemClock.elapsedRealtime():

long start = SystemClock.elapsedRealtime() + interval;

Technically the sample code could alternatively be changed to schedule an RTC_WAKEUP alarm instead an elapsed alarm. However it is not recommended to use RTC/RTC_WAKEUP inexact alarms because there is a very large population of devices that suffer from a bug that has only been fixed on ICS and Honeycomb 3.1+, but not previous devices. This bug will lead to RTC/RTC_WAKEUP alarms on Gingerbread and older devices closely aligning to the wall clock, firing ~30-45s after the top of the hour, or 15/30/45mins past the hour. The 30-45s offset depends on how many seconds after bootup the AppWidget Service initialises the first homescreen widget that has an updatePeriodMillis property of <30min, 30min, 1hr, 12hr or 24hr.

Why is this bad? For App developers it means they can experience traffic spikes on their servers when their Apps are woken by these alarms. For operators it means they may have hundreds of thousands of devices all trying to re-activate their radio from the IDLE state within a very short period, which creates cellular signalling storms on operator's infrastructure. This is exacerbated if the devices have their local time set automatically by the network.

ELAPSED_REALTIME and ELAPSED_REALTIME_WAKEUP inexact alarms will align to the device boot time + 30-45s, instead of the wall clock. Boot time should be randomly offset from the wall clock so these alarms will be evenly distributed across the device population on a network.

I'd therefore recommend the document strongly encourages the use of alarms in the elapsed time base instead of RTC.

For background info this bug was fixed here:
https://github.com/android/platform_frameworks_base/commit/b8849c1e858c726eaf04f7c5a5a08036faa171df