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
64template <typename Type>
65struct DefaultSingletonTraits;
66
67namespace base {
68namespace debug {
69
70// Time source for computing delay durations. Used for testing.
71class 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.
82class 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.
139TRACE_EVENT_API_CLASS_EXPORT void ResetTraceEventSyntheticDelays();
140
141}  // namespace debug
142}  // namespace base
143
144namespace trace_event_internal {
145
146// Helper class for scoped delays. Do not use directly.
147class 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.
161TRACE_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_ */
167