Home | History | Annotate | Download | only in trace_event 
      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_TRACE_EVENT_TRACE_EVENT_SYNTHETIC_DELAY_H_
     33 #define BASE_TRACE_EVENT_TRACE_EVENT_SYNTHETIC_DELAY_H_
     34 
     35 #include "base/atomicops.h"
     36 #include "base/macros.h"
     37 #include "base/synchronization/lock.h"
     38 #include "base/time/time.h"
     39 #include "base/trace_event/trace_event.h"
     40 
     41 // Apply a named delay in the current scope.
     42 #define TRACE_EVENT_SYNTHETIC_DELAY(name)                                     \
     43   static base::subtle::AtomicWord INTERNAL_TRACE_EVENT_UID(impl_ptr) = 0;     \
     44   trace_event_internal::ScopedSyntheticDelay INTERNAL_TRACE_EVENT_UID(delay)( \
     45       name, &INTERNAL_TRACE_EVENT_UID(impl_ptr));
     46 
     47 // Begin a named delay, establishing its timing start point. May be called
     48 // multiple times as long as the calls to TRACE_EVENT_SYNTHETIC_DELAY_END are
     49 // balanced. Only the first call records the timing start point.
     50 #define TRACE_EVENT_SYNTHETIC_DELAY_BEGIN(name)                          \
     51   do {                                                                   \
     52     static base::subtle::AtomicWord impl_ptr = 0;                        \
     53     trace_event_internal::GetOrCreateDelay(name, &impl_ptr)->Begin();    \
     54   } while (false)
     55 
     56 // End a named delay. The delay is applied only if this call matches the
     57 // first corresponding call to TRACE_EVENT_SYNTHETIC_DELAY_BEGIN with the
     58 // same delay.
     59 #define TRACE_EVENT_SYNTHETIC_DELAY_END(name)                         \
     60   do {                                                                \
     61     static base::subtle::AtomicWord impl_ptr = 0;                     \
     62     trace_event_internal::GetOrCreateDelay(name, &impl_ptr)->End();   \
     63   } while (false)
     64 
     65 template <typename Type>
     66 struct DefaultSingletonTraits;
     67 
     68 namespace base {
     69 namespace trace_event {
     70 
     71 // Time source for computing delay durations. Used for testing.
     72 class TRACE_EVENT_API_CLASS_EXPORT TraceEventSyntheticDelayClock {
     73  public:
     74   TraceEventSyntheticDelayClock();
     75   virtual ~TraceEventSyntheticDelayClock();
     76   virtual base::TimeTicks Now() = 0;
     77 
     78  private:
     79   DISALLOW_COPY_AND_ASSIGN(TraceEventSyntheticDelayClock);
     80 };
     81 
     82 // Single delay point instance.
     83 class TRACE_EVENT_API_CLASS_EXPORT TraceEventSyntheticDelay {
     84  public:
     85   enum Mode {
     86     STATIC,      // Apply the configured delay every time.
     87     ONE_SHOT,    // Apply the configured delay just once.
     88     ALTERNATING  // Apply the configured delay every other time.
     89   };
     90 
     91   // Returns an existing named delay instance or creates a new one with |name|.
     92   static TraceEventSyntheticDelay* Lookup(const std::string& name);
     93 
     94   void SetTargetDuration(TimeDelta target_duration);
     95   void SetMode(Mode mode);
     96   void SetClock(TraceEventSyntheticDelayClock* clock);
     97 
     98   // Begin the delay, establishing its timing start point. May be called
     99   // multiple times as long as the calls to End() are balanced. Only the first
    100   // call records the timing start point.
    101   void Begin();
    102 
    103   // End the delay. The delay is applied only if this call matches the first
    104   // corresponding call to Begin() with the same delay.
    105   void End();
    106 
    107   // Begin a parallel instance of the delay. Several parallel instances may be
    108   // active simultaneously and will complete independently. The computed end
    109   // time for the delay is stored in |out_end_time|, which should later be
    110   // passed to EndParallel().
    111   void BeginParallel(base::TimeTicks* out_end_time);
    112 
    113   // End a previously started parallel delay. |end_time| is the delay end point
    114   // computed by BeginParallel().
    115   void EndParallel(base::TimeTicks end_time);
    116 
    117  private:
    118   TraceEventSyntheticDelay();
    119   ~TraceEventSyntheticDelay();
    120   friend class TraceEventSyntheticDelayRegistry;
    121 
    122   void Initialize(const std::string& name,
    123                   TraceEventSyntheticDelayClock* clock);
    124   base::TimeTicks CalculateEndTimeLocked(base::TimeTicks start_time);
    125   void ApplyDelay(base::TimeTicks end_time);
    126 
    127   Lock lock_;
    128   Mode mode_;
    129   std::string name_;
    130   int begin_count_;
    131   int trigger_count_;
    132   base::TimeTicks end_time_;
    133   base::TimeDelta target_duration_;
    134   TraceEventSyntheticDelayClock* clock_;
    135 
    136   DISALLOW_COPY_AND_ASSIGN(TraceEventSyntheticDelay);
    137 };
    138 
    139 // Set the target durations of all registered synthetic delay points to zero.
    140 TRACE_EVENT_API_CLASS_EXPORT void ResetTraceEventSyntheticDelays();
    141 
    142 }  // namespace trace_event
    143 }  // namespace base
    144 
    145 namespace trace_event_internal {
    146 
    147 // Helper class for scoped delays. Do not use directly.
    148 class TRACE_EVENT_API_CLASS_EXPORT ScopedSyntheticDelay {
    149  public:
    150   explicit ScopedSyntheticDelay(const char* name,
    151                                 base::subtle::AtomicWord* impl_ptr);
    152   ~ScopedSyntheticDelay();
    153 
    154  private:
    155   base::trace_event::TraceEventSyntheticDelay* delay_impl_;
    156   base::TimeTicks end_time_;
    157 
    158   DISALLOW_COPY_AND_ASSIGN(ScopedSyntheticDelay);
    159 };
    160 
    161 // Helper for registering delays. Do not use directly.
    162 TRACE_EVENT_API_CLASS_EXPORT base::trace_event::TraceEventSyntheticDelay*
    163     GetOrCreateDelay(const char* name, base::subtle::AtomicWord* impl_ptr);
    164 
    165 }  // namespace trace_event_internal
    166 
    167 #endif  // BASE_TRACE_EVENT_TRACE_EVENT_SYNTHETIC_DELAY_H_
    168