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