cc/scheduler/begin_frame_tracker.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 CC_SCHEDULER_BEGIN_FRAME_TRACKER_H_
   6 #define CC_SCHEDULER_BEGIN_FRAME_TRACKER_H_
   7
   8 #include <set>
   9 #include <string>
  10
  11 #include "base/location.h"
  12 #include "base/trace_event/trace_event.h"
  13 #include "base/trace_event/trace_event_argument.h"
  14 #include "cc/output/begin_frame_args.h"
  15
  16 #define BEGINFRAMETRACKER_FROM_HERE FROM_HERE_WITH_EXPLICIT_FUNCTION("")
  17
  18 namespace cc {
  19
  20 // Microclass to trace and check properties for correct BeginFrameArgs (BFA)
  21 // usage and provide a few helper methods.
  22 //
  23 // With DCHECKs enable, this class checks the following "invariants";
  24 //  * BFA are monotonically increasing.
  25 //  * BFA is valid.
  26 //  * The BFA is only used inside a given period.
  27 //  * A new BFA isn't used before the last BFA is finished with.
  28 //
  29 // With the tracing category "cc.debug.scheduler.frames" enabled the tracker
  30 // will output the following trace information;
  31 //  * Time period for which the BFA is in usage.
  32 //  * The flow of BFA as they are passed between tracking objects.
  33 //
  34 // TODO(mithro): Record stats about the BeginFrameArgs
  35 class CC_EXPORT BeginFrameTracker {
  36  public:
  37   explicit BeginFrameTracker(const tracked_objects::Location& location);
  38   ~BeginFrameTracker();
  39
  40   // The Start and Finish methods manage the period that a BFA should be
  41   // accessed for. This allows tight control over the BFA and prevents
  42   // accidental usage in the wrong period when code is split across multiple
  43   // locations.
  44
  45   // Start using a new BFA value and check invariant properties.
  46   // **Must** only be called after finishing with any previous BFA.
  47   void Start(BeginFrameArgs new_args);
  48   // Finish using the current BFA.
  49   // **Must** only be called while still using a BFA.
  50   void Finish();
  51
  52   // The two accessors methods allow access to the BFA stored inside the
  53   // tracker. They are mutually exclusive, at any time it is only valid to call
  54   // one or the other. This makes sure you understand exactly which BFA you are
  55   // intending to use and verifies that is the case.
  56
  57   // Get the current BFA object.
  58   // **Must** only be called between the start and finish methods calls.
  59   const BeginFrameArgs& Current() const;
  60   // Get the last used BFA.
  61   // **Must** only be called when **not** between the start and finish method
  62   // calls.
  63   const BeginFrameArgs& Last() const;
  64
  65   // Helper method to try and return a valid interval property. Defaults to
  66   // BFA::DefaultInterval() is no other interval can be found. Can be called at
  67   // any time.
  68   base::TimeDelta Interval() const;
  69
  70   void AsValueInto(base::TimeTicks now,
  71                    base::trace_event::TracedValue* dict) const;
  72
  73   // The following methods violate principles of how BeginFrameArgs should be
  74   // used. These methods should only be used when there is no other choice.
  75   bool DangerousMethodHasStarted() const {
  76     return !current_updated_at_.is_null();
  77   }
  78   bool DangerousMethodHasFinished() const { return HasFinished(); }
  79   const BeginFrameArgs& DangerousMethodCurrentOrLast() const;
  80
  81  private:
  82   // Return if currently not between the start/end period. This method should
  83   // be used extremely sparingly and normal indicates incorrect management of
  84   // the BFA object. Can be called at any time.
  85   bool HasFinished() const { return !current_finished_at_.is_null(); }
  86
  87   const tracked_objects::Location location_;
  88   const std::string location_string_;
  89
  90   base::TraceTicks current_updated_at_;
  91   BeginFrameArgs current_args_;
  92   base::TraceTicks current_finished_at_;
  93 };
  94
  95 }  // namespace cc
  96
  97 #endif  // CC_SCHEDULER_BEGIN_FRAME_TRACKER_H_