extensions/browser/api/alarms/alarm_manager.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef EXTENSIONS_BROWSER_API_ALARMS_ALARM_MANAGER_H_
   6 #define EXTENSIONS_BROWSER_API_ALARMS_ALARM_MANAGER_H_
   7
   8 #include <map>
   9 #include <queue>
  10 #include <string>
  11 #include <vector>
  12
  13 #include "base/callback.h"
  14 #include "base/gtest_prod_util.h"
  15 #include "base/memory/weak_ptr.h"
  16 #include "base/scoped_observer.h"
  17 #include "base/timer/timer.h"
  18 #include "extensions/browser/browser_context_keyed_api_factory.h"
  19 #include "extensions/browser/extension_registry_observer.h"
  20 #include "extensions/common/api/alarms.h"
  21
  22 namespace base {
  23 class Clock;
  24 }  // namespace base
  25
  26 namespace content {
  27 class BrowserContext;
  28 }  // namespace content
  29
  30 namespace extensions {
  31 class ExtensionAlarmsSchedulingTest;
  32 class ExtensionRegistry;
  33
  34 struct Alarm {
  35   Alarm();
  36   Alarm(const std::string& name,
  37         const api::alarms::AlarmCreateInfo& create_info,
  38         base::TimeDelta min_granularity,
  39         base::Time now);
  40   ~Alarm();
  41
  42   linked_ptr<api::alarms::Alarm> js_alarm;
  43   // The granularity isn't exposed to the extension's javascript, but we poll at
  44   // least as often as the shortest alarm's granularity.  It's initialized as
  45   // the relative delay requested in creation, even if creation uses an absolute
  46   // time.  This will always be at least as large as the min_granularity
  47   // constructor argument.
  48   base::TimeDelta granularity;
  49   // The minimum granularity is the minimum allowed polling rate. This stops
  50   // alarms from polling too often.
  51   base::TimeDelta minimum_granularity;
  52 };
  53
  54 // Manages the currently pending alarms for every extension in a profile.
  55 // There is one manager per virtual Profile.
  56 class AlarmManager : public BrowserContextKeyedAPI,
  57                      public ExtensionRegistryObserver,
  58                      public base::SupportsWeakPtr<AlarmManager> {
  59  public:
  60   typedef std::vector<Alarm> AlarmList;
  61
  62   class Delegate {
  63    public:
  64     virtual ~Delegate() {}
  65     // Called when an alarm fires.
  66     virtual void OnAlarm(const std::string& extension_id,
  67                          const Alarm& alarm) = 0;
  68   };
  69
  70   explicit AlarmManager(content::BrowserContext* context);
  71   ~AlarmManager() override;
  72
  73   // Override the default delegate. Callee assumes onwership. Used for testing.
  74   void set_delegate(Delegate* delegate) { delegate_.reset(delegate); }
  75
  76   typedef base::Callback<void()> AddAlarmCallback;
  77   // Adds |alarm| for the given extension, and starts the timer. Invokes
  78   // |callback| when done.
  79   void AddAlarm(const std::string& extension_id,
  80                 const Alarm& alarm,
  81                 const AddAlarmCallback& callback);
  82
  83   typedef base::Callback<void(Alarm*)> GetAlarmCallback;
  84   // Passes the alarm with the given name, or NULL if none exists, to
  85   // |callback|.
  86   void GetAlarm(const std::string& extension_id,
  87                 const std::string& name,
  88                 const GetAlarmCallback& callback);
  89
  90   typedef base::Callback<void(const AlarmList*)> GetAllAlarmsCallback;
  91   // Passes the list of pending alarms for the given extension, or
  92   // NULL if none exist, to |callback|.
  93   void GetAllAlarms(const std::string& extension_id,
  94                     const GetAllAlarmsCallback& callback);
  95
  96   typedef base::Callback<void(bool)> RemoveAlarmCallback;
  97   // Cancels and removes the alarm with the given name. Invokes |callback| when
  98   // done.
  99   void RemoveAlarm(const std::string& extension_id,
 100                    const std::string& name,
 101                    const RemoveAlarmCallback& callback);
 102
 103   typedef base::Callback<void()> RemoveAllAlarmsCallback;
 104   // Cancels and removes all alarms for the given extension. Invokes |callback|
 105   // when done.
 106   void RemoveAllAlarms(const std::string& extension_id,
 107                        const RemoveAllAlarmsCallback& callback);
 108
 109   // Replaces AlarmManager's owned clock with |clock| and takes ownership of it.
 110   void SetClockForTesting(base::Clock* clock);
 111
 112   // BrowserContextKeyedAPI implementation.
 113   static BrowserContextKeyedAPIFactory<AlarmManager>* GetFactoryInstance();
 114
 115   // Convenience method to get the AlarmManager for a content::BrowserContext.
 116   static AlarmManager* Get(content::BrowserContext* browser_context);
 117
 118  private:
 119   friend void RunScheduleNextPoll(AlarmManager*);
 120   friend class ExtensionAlarmsSchedulingTest;
 121   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest, PollScheduling);
 122   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest,
 123                            ReleasedExtensionPollsInfrequently);
 124   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest, TimerRunning);
 125   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest, MinimumGranularity);
 126   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest,
 127                            DifferentMinimumGranularities);
 128   FRIEND_TEST_ALL_PREFIXES(ExtensionAlarmsSchedulingTest,
 129                            RepeatingAlarmsScheduledPredictably);
 130   friend class BrowserContextKeyedAPIFactory<AlarmManager>;
 131
 132   typedef std::string ExtensionId;
 133   typedef std::map<ExtensionId, AlarmList> AlarmMap;
 134
 135   typedef base::Callback<void(const std::string&)> ReadyAction;
 136   typedef std::queue<ReadyAction> ReadyQueue;
 137   typedef std::map<ExtensionId, ReadyQueue> ReadyMap;
 138
 139   // Iterator used to identify a particular alarm within the Map/List pair.
 140   // "Not found" is represented by <alarms_.end(), invalid_iterator>.
 141   typedef std::pair<AlarmMap::iterator, AlarmList::iterator> AlarmIterator;
 142
 143   // Part of AddAlarm that is executed after alarms are loaded.
 144   void AddAlarmWhenReady(const Alarm& alarm,
 145                          const AddAlarmCallback& callback,
 146                          const std::string& extension_id);
 147
 148   // Part of GetAlarm that is executed after alarms are loaded.
 149   void GetAlarmWhenReady(const std::string& name,
 150                          const GetAlarmCallback& callback,
 151                          const std::string& extension_id);
 152
 153   // Part of GetAllAlarms that is executed after alarms are loaded.
 154   void GetAllAlarmsWhenReady(const GetAllAlarmsCallback& callback,
 155                              const std::string& extension_id);
 156
 157   // Part of RemoveAlarm that is executed after alarms are loaded.
 158   void RemoveAlarmWhenReady(const std::string& name,
 159                             const RemoveAlarmCallback& callback,
 160                             const std::string& extension_id);
 161
 162   // Part of RemoveAllAlarms that is executed after alarms are loaded.
 163   void RemoveAllAlarmsWhenReady(const RemoveAllAlarmsCallback& callback,
 164                                 const std::string& extension_id);
 165
 166   // Helper to return the iterators within the AlarmMap and AlarmList for the
 167   // matching alarm, or an iterator to the end of the AlarmMap if none were
 168   // found.
 169   AlarmIterator GetAlarmIterator(const std::string& extension_id,
 170                                  const std::string& name);
 171
 172   // Helper to cancel and remove the alarm at the given iterator. The iterator
 173   // must be valid.
 174   void RemoveAlarmIterator(const AlarmIterator& iter);
 175
 176   // Callback for when an alarm fires.
 177   void OnAlarm(AlarmIterator iter);
 178
 179   // Internal helper to add an alarm and start the timer with the given delay.
 180   void AddAlarmImpl(const std::string& extension_id, const Alarm& alarm);
 181
 182   // Syncs our alarm data for the given extension to/from the state storage.
 183   void WriteToStorage(const std::string& extension_id);
 184   void ReadFromStorage(const std::string& extension_id,
 185                        scoped_ptr<base::Value> value);
 186
 187   // Set the timer to go off at the specified |time|, and set |next_poll_time|
 188   // appropriately.
 189   void SetNextPollTime(const base::Time& time);
 190
 191   // Schedules the next poll of alarms for when the next soonest alarm runs,
 192   // but not more often than the minimum granularity of all alarms.
 193   void ScheduleNextPoll();
 194
 195   // Polls the alarms, running any that have elapsed. After running them and
 196   // rescheduling repeating alarms, schedule the next poll.
 197   void PollAlarms();
 198
 199   // Executes |action| for given extension, making sure that the extension's
 200   // alarm data has been synced from the storage.
 201   void RunWhenReady(const std::string& extension_id, const ReadyAction& action);
 202
 203   // ExtensionRegistryObserver implementation.
 204   void OnExtensionLoaded(content::BrowserContext* browser_context,
 205                          const Extension* extension) override;
 206   void OnExtensionUninstalled(content::BrowserContext* browser_context,
 207                               const Extension* extension,
 208                               extensions::UninstallReason reason) override;
 209
 210   // BrowserContextKeyedAPI implementation.
 211   static const char* service_name() { return "AlarmManager"; }
 212   static const bool kServiceHasOwnInstanceInIncognito = true;
 213
 214   content::BrowserContext* const browser_context_;
 215   scoped_ptr<base::Clock> clock_;
 216   scoped_ptr<Delegate> delegate_;
 217
 218   // Listen to extension load notifications.
 219   ScopedObserver<ExtensionRegistry, ExtensionRegistryObserver>
 220       extension_registry_observer_;
 221
 222   // The timer for this alarm manager.
 223   base::OneShotTimer<AlarmManager> timer_;
 224
 225   // A map of our pending alarms, per extension.
 226   // Invariant: None of the AlarmLists are empty.
 227   AlarmMap alarms_;
 228
 229   // A map of actions waiting for alarm data to be synced from storage, per
 230   // extension.
 231   ReadyMap ready_actions_;
 232
 233   // The previous time that alarms were run.
 234   base::Time last_poll_time_;
 235
 236   // Next poll's time.
 237   base::Time next_poll_time_;
 238
 239   DISALLOW_COPY_AND_ASSIGN(AlarmManager);
 240 };
 241
 242 }  //  namespace extensions
 243
 244 #endif  // EXTENSIONS_BROWSER_API_ALARMS_ALARM_MANAGER_H_