/* * Copyright (C) 2009 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.android.common; import android.content.SharedPreferences; import android.text.format.Time; import java.util.Map; import java.util.TreeMap; /** * Tracks the success/failure history of a particular network operation in * persistent storage and computes retry strategy accordingly. Handles * exponential backoff, periodic rescheduling, event-driven triggering, * retry-after moratorium intervals, etc. based on caller-specified parameters. * *

This class does not directly perform or invoke any operations, * it only keeps track of the schedule. Somebody else needs to call * {@link #getNextTimeMillis} as appropriate and do the actual work. */ public class OperationScheduler { /** Tunable parameter options for {@link #getNextTimeMillis}. */ public static class Options { /** Wait this long after every error before retrying. */ public long backoffFixedMillis = 0; /** Wait this long times the number of consecutive errors so far before retrying. */ public long backoffIncrementalMillis = 5000; /** Wait this long times 2^(number of consecutive errors so far) before retrying. */ public int backoffExponentialMillis = 0; /** Maximum duration of moratorium to honor. Mostly an issue for clock rollbacks. */ public long maxMoratoriumMillis = 24 * 3600 * 1000; /** Minimum duration after success to wait before allowing another trigger. */ public long minTriggerMillis = 0; /** Automatically trigger this long after the last success. */ public long periodicIntervalMillis = 0; @Override public String toString() { if (backoffExponentialMillis > 0) { return String.format( "OperationScheduler.Options[backoff=%.1f+%.1f+%.1f max=%.1f min=%.1f period=%.1f]", backoffFixedMillis / 1000.0, backoffIncrementalMillis / 1000.0, backoffExponentialMillis / 1000.0, maxMoratoriumMillis / 1000.0, minTriggerMillis / 1000.0, periodicIntervalMillis / 1000.0); } else { return String.format( "OperationScheduler.Options[backoff=%.1f+%.1f max=%.1f min=%.1f period=%.1f]", backoffFixedMillis / 1000.0, backoffIncrementalMillis / 1000.0, maxMoratoriumMillis / 1000.0, minTriggerMillis / 1000.0, periodicIntervalMillis / 1000.0); } } } private static final String PREFIX = "OperationScheduler_"; private final SharedPreferences mStorage; /** * Initialize the scheduler state. * @param storage to use for recording the state of operations across restarts/reboots */ public OperationScheduler(SharedPreferences storage) { mStorage = storage; } /** * Parse scheduler options supplied in this string form: * *

     * backoff=(fixed)+(incremental)[+(exponential)] max=(maxmoratorium) min=(mintrigger) [period=](interval)
     * 
* * All values are times in (possibly fractional) seconds (not milliseconds). * Omitted settings are left at whatever existing default value was passed in. * *

* The default options: backoff=0+5 max=86400 min=0 period=0
* Fractions are OK: backoff=+2.5 period=10.0
* The "period=" can be omitted: 3600
* * @param spec describing some or all scheduler options. * @param options to update with parsed values. * @return the options passed in (for convenience) * @throws IllegalArgumentException if the syntax is invalid */ public static Options parseOptions(String spec, Options options) throws IllegalArgumentException { for (String param : spec.split(" +")) { if (param.length() == 0) continue; if (param.startsWith("backoff=")) { String[] pieces = param.substring(8).split("\\+"); if (pieces.length > 3) { throw new IllegalArgumentException("bad value for backoff: [" + spec + "]"); } if (pieces.length > 0 && pieces[0].length() > 0) { options.backoffFixedMillis = parseSeconds(pieces[0]); } if (pieces.length > 1 && pieces[1].length() > 0) { options.backoffIncrementalMillis = parseSeconds(pieces[1]); } if (pieces.length > 2 && pieces[2].length() > 0) { options.backoffExponentialMillis = (int)parseSeconds(pieces[2]); } } else if (param.startsWith("max=")) { options.maxMoratoriumMillis = parseSeconds(param.substring(4)); } else if (param.startsWith("min=")) { options.minTriggerMillis = parseSeconds(param.substring(4)); } else if (param.startsWith("period=")) { options.periodicIntervalMillis = parseSeconds(param.substring(7)); } else { options.periodicIntervalMillis = parseSeconds(param); } } return options; } private static long parseSeconds(String param) throws NumberFormatException { return (long) (Float.parseFloat(param) * 1000); } /** * Compute the time of the next operation. Does not modify any state * (unless the clock rolls backwards, in which case timers are reset). * * @param options to use for this computation. * @return the wall clock time ({@link System#currentTimeMillis()}) when the * next operation should be attempted -- immediately, if the return value is * before the current time. */ public long getNextTimeMillis(Options options) { boolean enabledState = mStorage.getBoolean(PREFIX + "enabledState", true); if (!enabledState) return Long.MAX_VALUE; boolean permanentError = mStorage.getBoolean(PREFIX + "permanentError", false); if (permanentError) return Long.MAX_VALUE; // We do quite a bit of limiting to prevent a clock rollback from totally // hosing the scheduler. Times which are supposed to be in the past are // clipped to the current time so we don't languish forever. int errorCount = mStorage.getInt(PREFIX + "errorCount", 0); long now = currentTimeMillis(); long lastSuccessTimeMillis = getTimeBefore(PREFIX + "lastSuccessTimeMillis", now); long lastErrorTimeMillis = getTimeBefore(PREFIX + "lastErrorTimeMillis", now); long triggerTimeMillis = mStorage.getLong(PREFIX + "triggerTimeMillis", Long.MAX_VALUE); long moratoriumSetMillis = getTimeBefore(PREFIX + "moratoriumSetTimeMillis", now); long moratoriumTimeMillis = getTimeBefore(PREFIX + "moratoriumTimeMillis", moratoriumSetMillis + options.maxMoratoriumMillis); long time = triggerTimeMillis; if (options.periodicIntervalMillis > 0) { time = Math.min(time, lastSuccessTimeMillis + options.periodicIntervalMillis); } time = Math.max(time, moratoriumTimeMillis); time = Math.max(time, lastSuccessTimeMillis + options.minTriggerMillis); if (errorCount > 0) { int shift = errorCount-1; // backoffExponentialMillis is an int, so we can safely // double it 30 times without overflowing a long. if (shift > 30) shift = 30; long backoff = options.backoffFixedMillis + (options.backoffIncrementalMillis * errorCount) + (((long)options.backoffExponentialMillis) << shift); // Treat backoff like a moratorium: don't let the backoff time grow too large. backoff = Math.min(backoff, options.maxMoratoriumMillis); time = Math.max(time, lastErrorTimeMillis + backoff); } return time; } /** * Return the last time the operation completed. Does not modify any state. * * @return the wall clock time when {@link #onSuccess()} was last called. */ public long getLastSuccessTimeMillis() { return mStorage.getLong(PREFIX + "lastSuccessTimeMillis", 0); } /** * Return the last time the operation was attempted. Does not modify any state. * * @return the wall clock time when {@link #onSuccess()} or {@link * #onTransientError()} was last called. */ public long getLastAttemptTimeMillis() { return Math.max( mStorage.getLong(PREFIX + "lastSuccessTimeMillis", 0), mStorage.getLong(PREFIX + "lastErrorTimeMillis", 0)); } /** * Fetch a {@link SharedPreferences} property, but force it to be before * a certain time, updating the value if necessary. This is to recover * gracefully from clock rollbacks which could otherwise strand our timers. * * @param name of SharedPreferences key * @param max time to allow in result * @return current value attached to key (default 0), limited by max */ private long getTimeBefore(String name, long max) { long time = mStorage.getLong(name, 0); if (time > max) { time = max; SharedPreferencesCompat.apply(mStorage.edit().putLong(name, time)); } return time; } /** * Request an operation to be performed at a certain time. The actual * scheduled time may be affected by error backoff logic and defined * minimum intervals. Use {@link Long#MAX_VALUE} to disable triggering. * * @param millis wall clock time ({@link System#currentTimeMillis()}) to * trigger another operation; 0 to trigger immediately */ public void setTriggerTimeMillis(long millis) { SharedPreferencesCompat.apply( mStorage.edit().putLong(PREFIX + "triggerTimeMillis", millis)); } /** * Forbid any operations until after a certain (absolute) time. * Limited by {@link Options#maxMoratoriumMillis}. * * @param millis wall clock time ({@link System#currentTimeMillis()}) * when operations should be allowed again; 0 to remove moratorium */ public void setMoratoriumTimeMillis(long millis) { SharedPreferencesCompat.apply(mStorage.edit() .putLong(PREFIX + "moratoriumTimeMillis", millis) .putLong(PREFIX + "moratoriumSetTimeMillis", currentTimeMillis())); } /** * Forbid any operations until after a certain time, as specified in * the format used by the HTTP "Retry-After" header. * Limited by {@link Options#maxMoratoriumMillis}. * * @param retryAfter moratorium time in HTTP format * @return true if a time was successfully parsed */ public boolean setMoratoriumTimeHttp(String retryAfter) { try { long ms = Long.parseLong(retryAfter) * 1000; setMoratoriumTimeMillis(ms + currentTimeMillis()); return true; } catch (NumberFormatException nfe) { try { setMoratoriumTimeMillis(LegacyHttpDateTime.parse(retryAfter)); return true; } catch (IllegalArgumentException iae) { return false; } } } /** * Enable or disable all operations. When disabled, all calls to * {@link #getNextTimeMillis} return {@link Long#MAX_VALUE}. * Commonly used when data network availability goes up and down. * * @param enabled if operations can be performed */ public void setEnabledState(boolean enabled) { SharedPreferencesCompat.apply( mStorage.edit().putBoolean(PREFIX + "enabledState", enabled)); } /** * Report successful completion of an operation. Resets all error * counters, clears any trigger directives, and records the success. */ public void onSuccess() { resetTransientError(); resetPermanentError(); SharedPreferencesCompat.apply(mStorage.edit() .remove(PREFIX + "errorCount") .remove(PREFIX + "lastErrorTimeMillis") .remove(PREFIX + "permanentError") .remove(PREFIX + "triggerTimeMillis") .putLong(PREFIX + "lastSuccessTimeMillis", currentTimeMillis())); } /** * Report a transient error (usually a network failure). Increments * the error count and records the time of the latest error for backoff * purposes. */ public void onTransientError() { SharedPreferences.Editor editor = mStorage.edit(); editor.putLong(PREFIX + "lastErrorTimeMillis", currentTimeMillis()); editor.putInt(PREFIX + "errorCount", mStorage.getInt(PREFIX + "errorCount", 0) + 1); SharedPreferencesCompat.apply(editor); } /** * Reset all transient error counts, allowing the next operation to proceed * immediately without backoff. Commonly used on network state changes, when * partial progress occurs (some data received), and in other circumstances * where there is reason to hope things might start working better. */ public void resetTransientError() { SharedPreferencesCompat.apply(mStorage.edit().remove(PREFIX + "errorCount")); } /** * Report a permanent error that will not go away until further notice. * No operation will be scheduled until {@link #resetPermanentError()} * is called. Commonly used for authentication failures (which are reset * when the accounts database is updated). */ public void onPermanentError() { SharedPreferencesCompat.apply(mStorage.edit().putBoolean(PREFIX + "permanentError", true)); } /** * Reset any permanent error status set by {@link #onPermanentError}, * allowing operations to be scheduled as normal. */ public void resetPermanentError() { SharedPreferencesCompat.apply(mStorage.edit().remove(PREFIX + "permanentError")); } /** * Return a string description of the scheduler state for debugging. */ public String toString() { StringBuilder out = new StringBuilder("[OperationScheduler:"); TreeMap copy = new TreeMap(mStorage.getAll()); // Sort keys for (Map.Entry e : copy.entrySet()) { String key = e.getKey(); if (key.startsWith(PREFIX)) { if (key.endsWith("TimeMillis")) { Time time = new Time(); time.set((Long) e.getValue()); out.append(" ").append(key.substring(PREFIX.length(), key.length() - 10)); out.append("=").append(time.format("%Y-%m-%d/%H:%M:%S")); } else { out.append(" ").append(key.substring(PREFIX.length())); Object v = e.getValue(); if (v == null) { out.append("=(null)"); } else { out.append("=").append(v.toString()); } } } } return out.append("]").toString(); } /** * Gets the current time. Can be overridden for unit testing. * * @return {@link System#currentTimeMillis()} */ protected long currentTimeMillis() { return System.currentTimeMillis(); } }