base/debug/trace_event_synthetic_delay.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 // The synthetic delay framework makes it possible to dynamically inject
   6 // arbitrary delays into into different parts of the codebase. This can be used,
   7 // for instance, for testing various task scheduling algorithms.
   8 //
   9 // The delays are specified in terms of a target duration for a given block of
  10 // code. If the code executes faster than the duration, the thread is made to
  11 // sleep until the deadline is met.
  12 //
  13 // Code can be instrumented for delays with two sets of macros. First, for
  14 // delays that should apply within a scope, use the following macro:
  15 //
  16 //   TRACE_EVENT_SYNTHETIC_DELAY("cc.LayerTreeHost.DrawAndSwap");
  17 //
  18 // For delaying operations that span multiple scopes, use:
  19 //
  20 //   TRACE_EVENT_SYNTHETIC_DELAY_BEGIN("cc.Scheduler.BeginMainFrame");
  21 //   ...
  22 //   TRACE_EVENT_SYNTHETIC_DELAY_END("cc.Scheduler.BeginMainFrame");
  23 //
  24 // Here BEGIN establishes the start time for the delay and END executes the
  25 // delay based on the remaining time. If BEGIN is called multiple times in a
  26 // row, END should be called a corresponding number of times. Only the last
  27 // call to END will have an effect.
  28 //
  29 // Note that a single delay may begin on one thread and end on another. This
  30 // implies that a single delay cannot not be applied in several threads at once.
  31
  32 #ifndef BASE_DEBUG_TRACE_EVENT_SYNTHETIC_DELAY_H_
  33 #define BASE_DEBUG_TRACE_EVENT_SYNTHETIC_DELAY_H_
  34
  35 #include "base/atomicops.h"
  36 #include "base/debug/trace_event.h"
  37 #include "base/synchronization/lock.h"
  38 #include "base/time/time.h"
  39
  40 // Apply a named delay in the current scope.
  41 #define TRACE_EVENT_SYNTHETIC_DELAY(name)                                     \
  42   static base::subtle::AtomicWord INTERNAL_TRACE_EVENT_UID(impl_ptr) = 0;     \
  43   trace_event_internal::ScopedSyntheticDelay INTERNAL_TRACE_EVENT_UID(delay)( \
  44       name, &INTERNAL_TRACE_EVENT_UID(impl_ptr));
  45
  46 // Begin a named delay, establishing its timing start point. May be called
  47 // multiple times as long as the calls to TRACE_EVENT_SYNTHETIC_DELAY_END are
  48 // balanced. Only the first call records the timing start point.
  49 #define TRACE_EVENT_SYNTHETIC_DELAY_BEGIN(name)                          \
  50   do {                                                                   \
  51     static base::subtle::AtomicWord impl_ptr = 0;                        \
  52     trace_event_internal::GetOrCreateDelay(name, &impl_ptr)->Begin();    \
  53   } while (false)
  54
  55 // End a named delay. The delay is applied only if this call matches the
  56 // first corresponding call to TRACE_EVENT_SYNTHETIC_DELAY_BEGIN with the
  57 // same delay.
  58 #define TRACE_EVENT_SYNTHETIC_DELAY_END(name)                         \
  59   do {                                                                \
  60     static base::subtle::AtomicWord impl_ptr = 0;                     \
  61     trace_event_internal::GetOrCreateDelay(name, &impl_ptr)->End();   \
  62   } while (false)
  63
  64 template <typename Type>
  65 struct DefaultSingletonTraits;
  66
  67 namespace base {
  68 namespace debug {
  69
  70 // Time source for computing delay durations. Used for testing.
  71 class TRACE_EVENT_API_CLASS_EXPORT TraceEventSyntheticDelayClock {
  72  public:
  73   TraceEventSyntheticDelayClock();
  74   virtual ~TraceEventSyntheticDelayClock();
  75   virtual base::TimeTicks Now() = 0;
  76
  77  private:
  78   DISALLOW_COPY_AND_ASSIGN(TraceEventSyntheticDelayClock);
  79 };
  80
  81 // Single delay point instance.
  82 class TRACE_EVENT_API_CLASS_EXPORT TraceEventSyntheticDelay {
  83  public:
  84   enum Mode {
  85     STATIC,      // Apply the configured delay every time.
  86     ONE_SHOT,    // Apply the configured delay just once.
  87     ALTERNATING  // Apply the configured delay every other time.
  88   };
  89
  90   // Returns an existing named delay instance or creates a new one with |name|.
  91   static TraceEventSyntheticDelay* Lookup(const std::string& name);
  92
  93   void SetTargetDuration(TimeDelta target_duration);
  94   void SetMode(Mode mode);
  95   void SetClock(TraceEventSyntheticDelayClock* clock);
  96
  97   // Begin the delay, establishing its timing start point. May be called
  98   // multiple times as long as the calls to End() are balanced. Only the first
  99   // call records the timing start point.
 100   void Begin();
 101
 102   // End the delay. The delay is applied only if this call matches the first
 103   // corresponding call to Begin() with the same delay.
 104   void End();
 105
 106   // Begin a parallel instance of the delay. Several parallel instances may be
 107   // active simultaneously and will complete independently. The computed end
 108   // time for the delay is stored in |out_end_time|, which should later be
 109   // passed to EndParallel().
 110   void BeginParallel(base::TimeTicks* out_end_time);
 111
 112   // End a previously started parallel delay. |end_time| is the delay end point
 113   // computed by BeginParallel().
 114   void EndParallel(base::TimeTicks end_time);
 115
 116  private:
 117   TraceEventSyntheticDelay();
 118   ~TraceEventSyntheticDelay();
 119   friend class TraceEventSyntheticDelayRegistry;
 120
 121   void Initialize(const std::string& name,
 122                   TraceEventSyntheticDelayClock* clock);
 123   base::TimeTicks CalculateEndTimeLocked(base::TimeTicks start_time);
 124   void ApplyDelay(base::TimeTicks end_time);
 125
 126   Lock lock_;
 127   Mode mode_;
 128   std::string name_;
 129   int begin_count_;
 130   int trigger_count_;
 131   base::TimeTicks end_time_;
 132   base::TimeDelta target_duration_;
 133   TraceEventSyntheticDelayClock* clock_;
 134
 135   DISALLOW_COPY_AND_ASSIGN(TraceEventSyntheticDelay);
 136 };
 137
 138 // Set the target durations of all registered synthetic delay points to zero.
 139 TRACE_EVENT_API_CLASS_EXPORT void ResetTraceEventSyntheticDelays();
 140
 141 }  // namespace debug
 142 }  // namespace base
 143
 144 namespace trace_event_internal {
 145
 146 // Helper class for scoped delays. Do not use directly.
 147 class TRACE_EVENT_API_CLASS_EXPORT ScopedSyntheticDelay {
 148  public:
 149   explicit ScopedSyntheticDelay(const char* name,
 150                                 base::subtle::AtomicWord* impl_ptr);
 151   ~ScopedSyntheticDelay();
 152
 153  private:
 154   base::debug::TraceEventSyntheticDelay* delay_impl_;
 155   base::TimeTicks end_time_;
 156
 157   DISALLOW_COPY_AND_ASSIGN(ScopedSyntheticDelay);
 158 };
 159
 160 // Helper for registering delays. Do not use directly.
 161 TRACE_EVENT_API_CLASS_EXPORT base::debug::TraceEventSyntheticDelay*
 162     GetOrCreateDelay(const char* name, base::subtle::AtomicWord* impl_ptr);
 163
 164 }  // namespace trace_event_internal
 165
 166 #endif /* BASE_DEBUG_TRACE_EVENT_SYNTHETIC_DELAY_H_ */