components/metrics/daily_event.h

   1 // Copyright 2014 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 COMPONENTS_METRICS_DAILY_EVENT_H_
   6 #define COMPONENTS_METRICS_DAILY_EVENT_H_
   7
   8 #include "base/macros.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "base/memory/scoped_vector.h"
  11 #include "base/time/time.h"
  12
  13 class PrefRegistrySimple;
  14 class PrefService;
  15
  16 namespace metrics {
  17
  18 // DailyEvent is used for throttling an event to about once per day, even if
  19 // the program is restarted more frequently.  It is based on local machine
  20 // time, so it could be fired more often if the clock is changed.
  21 //
  22 // The service using the DailyEvent should first provide all of the Observers
  23 // for the interval, and then arrange for CheckInterval() to be called
  24 // periodically to test if the event should be fired.
  25 class DailyEvent {
  26  public:
  27   // Observer receives notifications from a DailyEvent.
  28   // Observers must be added before the DailyEvent begins checking time,
  29   // and will be owned by the DailyEvent.
  30   class Observer {
  31    public:
  32     Observer();
  33     virtual ~Observer();
  34
  35     // Called when the daily event is fired.
  36     virtual void OnDailyEvent() = 0;
  37
  38    private:
  39     DISALLOW_COPY_AND_ASSIGN(Observer);
  40   };
  41
  42   // Constructs DailyEvent monitor which stores the time it last fired in the
  43   // preference |pref_name|. |pref_name| should be registered by calling
  44   // RegisterPref before using this object.
  45   // Caller is responsible for ensuring that |pref_service| and |pref_name|
  46   // outlive the DailyEvent.
  47   // |histogram_name| is the name of the UMA metric which record when this
  48   // interval fires, and should be registered in histograms.xml
  49   DailyEvent(PrefService* pref_service,
  50              const char* pref_name,
  51              const std::string& histogram_name);
  52   ~DailyEvent();
  53
  54   // Adds a observer to be notified when a day elapses. All observers should
  55   // be registered before the the DailyEvent starts checking time.
  56   void AddObserver(scoped_ptr<Observer> observer);
  57
  58   // Checks if a day has elapsed. If it has, OnDailyEvent will be called on
  59   // all observers.
  60   void CheckInterval();
  61
  62   // Registers the preference used by this interval.
  63   static void RegisterPref(PrefRegistrySimple* registry, const char* pref_name);
  64
  65  private:
  66   // Handles an interval elapsing.
  67   void OnInterval(base::Time now);
  68
  69   // A weak pointer to the PrefService object to read and write preferences
  70   // from. Calling code should ensure this object continues to exist for the
  71   // lifetime of the DailyEvent object.
  72   PrefService* pref_service_;
  73
  74   // The name of the preference to store the last fired time in.
  75   // Calling code should ensure this outlives the DailyEvent.
  76   const char* pref_name_;
  77
  78   // The name of the histogram to record intervals.
  79   std::string histogram_name_;
  80
  81   // A list of observers.
  82   ScopedVector<Observer> observers_;
  83
  84   // The time that the daily event was last fired.
  85   base::Time last_fired_;
  86
  87   DISALLOW_COPY_AND_ASSIGN(DailyEvent);
  88 };
  89
  90 }  // namespace metrics
  91
  92 #endif  // COMPONENTS_METRICS_DAILY_EVENT_H_