media/capture/feedback_signal_accumulator.h

   1 // Copyright (c) 2015 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 MEDIA_CAPTURE_FEEDBACK_SIGNAL_ACCUMULATOR_H_
   6 #define MEDIA_CAPTURE_FEEDBACK_SIGNAL_ACCUMULATOR_H_
   7
   8 #include "base/time/time.h"
   9 #include "media/base/media_export.h"
  10
  11 namespace media {
  12
  13 // Utility class for maintaining an exponentially-decaying average of feedback
  14 // signal values whose updates occur at undetermined, possibly irregular time
  15 // intervals.
  16 //
  17 // Feedback signals can be made by multiple sources.  Meaning, there can be
  18 // several values provided for the same timestamp.  In this case, the greatest
  19 // value is retained and used to re-compute the average.  Therefore, the values
  20 // provided to this class' methods should be appropriately translated with this
  21 // in mind.  For example, an "fraction available" metric should be translated
  22 // into a "fraction utilized" one.
  23 //
  24 // Usage note: Reset() must be called at least once before the first call to
  25 // Update().
  26 class MEDIA_EXPORT FeedbackSignalAccumulator {
  27  public:
  28   // |half_life| is the amount of time that must pass between two data points to
  29   // move the accumulated average value halfway in-between.  Example: If
  30   // |half_life| is one second, then calling Reset(0.0, t=0s) and then
  31   // Update(1.0, t=1s) will result in an accumulated average value of 0.5.
  32   explicit FeedbackSignalAccumulator(base::TimeDelta half_life);
  33
  34   // Erase all memory of historical values, re-starting with the given
  35   // |starting_value|.
  36   void Reset(double starting_value, base::TimeTicks timestamp);
  37   base::TimeTicks reset_time() const { return reset_time_; }
  38
  39   // Apply the given |value|, which was observed at the given |timestamp|, to
  40   // the accumulated average.  If the timestamp is in chronological order, the
  41   // update succeeds and this method returns true.  Otherwise the update has no
  42   // effect and false is returned.  If there are two or more updates at the same
  43   // |timestamp|, only the one with the greatest value will be accounted for
  44   // (see class comments for elaboration).
  45   bool Update(double value, base::TimeTicks timestamp);
  46   base::TimeTicks update_time() const { return update_time_; }
  47
  48   // Returns the current accumulated average value.
  49   double current() const { return average_; }
  50
  51  private:
  52   // In conjunction with the |update_time_| and |prior_update_time_|, this is
  53   // used to compute the weight of the current update value versus the prior
  54   // accumulated average.
  55   const base::TimeDelta half_life_;
  56
  57   base::TimeTicks reset_time_;  // |timestamp| passed in last call to Reset().
  58   double average_;  // Current accumulated average.
  59   double update_value_;  // Latest |value| accepted by Update().
  60   base::TimeTicks update_time_;  // Latest |timestamp| accepted by Update().
  61   double prior_average_;  // Accumulated average before last call to Update().
  62   base::TimeTicks prior_update_time_;  // |timestamp| in prior call to Update().
  63 };
  64
  65 }  // namespace media
  66
  67 #endif  // MEDIA_CAPTURE_FEEDBACK_SIGNAL_ACCUMULATOR_H_