This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
trace.h
Go to the documentation of this file.
1//
2// Copyright 2018 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7
8#ifndef PXR_BASE_TRACE_TRACE_H
9#define PXR_BASE_TRACE_TRACE_H
10
12
13#include "pxr/pxr.h"
14
15#include "pxr/base/trace/api.h"
16#include "pxr/base/trace/collector.h"
17
18#include "pxr/base/tf/preprocessorUtilsLite.h"
19
20#include <atomic>
21
22#if !defined(TRACE_DISABLE)
23
26#define TRACE_FUNCTION() \
27 _TRACE_FUNCTION_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__)
28
31#define TRACE_SCOPE(name) \
32 _TRACE_SCOPE_INSTANCE(__LINE__, name)
33
36#define TRACE_FUNCTION_SCOPE(name) \
37 _TRACE_FUNCTION_SCOPE_INSTANCE( \
38 __LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__, name)
39
41#define TRACE_MARKER(name) \
42 _TRACE_MARKER_INSTANCE(__LINE__, name)
43
45#define TRACE_MARKER_DYNAMIC(name) \
46 _TRACE_MARKER_DYNAMIC_INSTANCE(__LINE__, name)
47
53#define TRACE_COUNTER_DELTA(name, delta) \
54 _TRACE_COUNTER_INSTANCE(__LINE__, name, delta, /* isDelta */ true)
55
60#define TRACE_COUNTER_DELTA_DYNAMIC(name, delta) \
61 TraceCollector::GetInstance().RecordCounterDelta(name, delta);
62
66#define TRACE_COUNTER_VALUE(name, value) \
67 _TRACE_COUNTER_INSTANCE(__LINE__, name, value, /* isDelta */ false)
68
73#define TRACE_COUNTER_VALUE_DYNAMIC(name, value) \
74 TraceCollector::GetInstance().RecordCounterValue(name, value);
75
94#define TRACE_COUNTER_DELTA_CODE(name, code) \
95 _TRACE_COUNTER_CODE_INSTANCE(__LINE__, name, code, true)
96
102#define TRACE_FUNCTION_DYNAMIC(name) \
103 _TRACE_FUNCTION_DYNAMIC_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__, name)
104
110#define TRACE_SCOPE_DYNAMIC(name) \
111 _TRACE_SCOPE_DYNAMIC_INSTANCE(__LINE__, name)
112
113
118
119
120#define _TRACE_FUNCTION_INSTANCE(instance, name, prettyName) \
121constexpr static PXR_NS::TraceStaticKeyData \
122 TF_PP_CAT(TraceKeyData_, instance)(name, prettyName); \
123PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
124 TF_PP_CAT(TraceKeyData_, instance));
125
126#define _TRACE_SCOPE_INSTANCE(instance, name) \
127constexpr static PXR_NS::TraceStaticKeyData \
128 TF_PP_CAT(TraceKeyData_, instance)(name); \
129PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
130 TF_PP_CAT(TraceKeyData_, instance));
131
132#define _TRACE_FUNCTION_SCOPE_INSTANCE(instance, name, prettyName, scopeName) \
133constexpr static PXR_NS::TraceStaticKeyData \
134 TF_PP_CAT(TraceKeyData_, instance)(name, prettyName, scopeName); \
135PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
136 TF_PP_CAT(TraceKeyData_, instance));
137
138#define _TRACE_MARKER_INSTANCE(instance, name) \
139constexpr static PXR_NS::TraceStaticKeyData \
140 TF_PP_CAT(TraceKeyData_, instance)(name); \
141 TraceCollector::GetInstance().MarkerEventStatic(TF_PP_CAT(TraceKeyData_, instance));
142
143#define _TRACE_COUNTER_INSTANCE(instance, name, value, isDelta) \
144constexpr static PXR_NS::TraceStaticKeyData \
145 TF_PP_CAT(TraceKeyData_, instance)(name); \
146static PXR_NS::TraceCounterHolder \
147 TF_PP_CAT(TraceCounterHolder_, instance) \
148 (TF_PP_CAT(TraceKeyData_, instance)); \
149TF_PP_CAT(TraceCounterHolder_, instance).Record(value, isDelta);
150
151#define _TRACE_COUNTER_CODE_INSTANCE(instance, name, code, isDelta) \
152static PXR_NS::TraceCounterHolder \
153 TF_PP_CAT(TraceCounterHolder_, instance)(name); \
154if (TF_PP_CAT(TraceCounterHolder_, instance).IsEnabled()) { \
155 double value = 0.0; \
156 code \
157 TF_PP_CAT(TraceCounterHolder_, instance).RecordDelta(value, isDelta); \
158}
159
160#define _TRACE_FUNCTION_DYNAMIC_INSTANCE(instance, fnName, fnPrettyName, name) \
161PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(fnName, fnPrettyName, name)
162
163#define _TRACE_SCOPE_DYNAMIC_INSTANCE(instance, str) \
164PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(str)
165
166#define _TRACE_MARKER_DYNAMIC_INSTANCE(instance, name) \
167 TraceCollector::GetInstance().MarkerEvent(name);
168
169#else // TRACE_DISABLE
170
171#define TRACE_FUNCTION()
172#define TRACE_FUNCTION_DYNAMIC(name)
173#define TRACE_SCOPE(name)
174#define TRACE_SCOPE_DYNAMIC(name)
175#define TRACE_FUNCTION_SCOPE(name)
176#define TRACE_MARKER(name)
177#define TRACE_MARKER_DYNAMIC(name)
178
179#endif // TRACE_DISABLE
180
181PXR_NAMESPACE_OPEN_SCOPE
182
190public:
193 explicit TraceScopeAuto(const TraceStaticKeyData& key) noexcept
194 : _key(&key)
195 , _intervalTimer(/*start=*/TraceCollector::IsEnabled()) {
196 }
197
200 template < typename... Args>
201 TraceScopeAuto(const TraceStaticKeyData& key, Args&&... args)
202 : _key(&key)
203 , _intervalTimer(/*start=*/false) {
205 _intervalTimer.Start();
206 TraceCollector
207 ::GetInstance().ScopeArgs(std::forward<Args>(args)...);
208 }
209 }
210
213 ~TraceScopeAuto() noexcept {
214 if (_intervalTimer.IsStarted()) {
215 TraceCollector::TimeStamp stopTicks =
216 _intervalTimer.GetCurrentTicks();
218 *_key, _intervalTimer.GetStartTicks(), stopTicks);
219 }
220 }
221
222private:
223 const TraceStaticKeyData* const _key;
224 ArchIntervalTimer _intervalTimer;
225};
226
238struct TraceAuto {
241 TraceAuto(const char *funcName, const char *prettyFuncName,
242 const std::string &name)
243 : _key(_CreateKeyString(funcName, prettyFuncName, name)) {
244 std::atomic_thread_fence(std::memory_order_seq_cst);
245 _collector = &TraceCollector::GetInstance();
246 _collector->BeginEvent(_key);
247 std::atomic_thread_fence(std::memory_order_seq_cst);
248 }
249
252 explicit TraceAuto(const TfToken& key)
253 : _key(key) {
254 std::atomic_thread_fence(std::memory_order_seq_cst);
255 _collector = &TraceCollector::GetInstance();
256 _collector->BeginEvent(_key);
257 std::atomic_thread_fence(std::memory_order_seq_cst);
258 }
259
262 explicit TraceAuto(const std::string& key)
263 : TraceAuto(TfToken(key)) {}
264
265 // Non-copyable
266 //
267 TraceAuto(const TraceAuto &) = delete;
268 TraceAuto& operator=(const TraceAuto &) = delete;
269
270 // Non-movable
271 //
272 TraceAuto(TraceAuto &&) = delete;
273 TraceAuto& operator=(TraceAuto &&) = delete;
274
278 std::atomic_thread_fence(std::memory_order_seq_cst);
279 _collector->EndEvent(_key);
280 std::atomic_thread_fence(std::memory_order_seq_cst);
281 }
282
283private:
284 static std::string _CreateKeyString(
285 const char *funcName,
286 const char *prettyFuncName,
287 const std::string &name) {
288 std::string key = ArchGetPrettierFunctionName(funcName, prettyFuncName);
289 key += " [";
290 key += name;
291 key += "]";
292 return key;
293 }
294
295 TraceCollector* _collector;
296 TraceDynamicKey _key;
297};
298
306public:
309 explicit TraceCounterHolder(const TraceKey& key)
310 : _key(key) {}
311
314 bool IsEnabled() const {
316 }
317
320 void Record(double value, bool delta) {
321 if (delta) {
323 } else {
325 }
326 }
327
328private:
329 TraceKey _key;
330};
331
332PXR_NAMESPACE_CLOSE_SCOPE
333
334#endif // PXR_BASE_TRACE_TRACE_H
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
This is a singleton class that records TraceEvent instances and populates TraceCollection instances.
Definition: collector.h:54
void RecordCounterDelta(const TraceKey &key, double delta)
Record a counter delta for a name key if Category is enabled.
Definition: collector.h:337
TimeStamp EndEvent(const Key &key)
Record an end event with key if Category is enabled.
Definition: collector.h:148
static TRACE_API void Scope(const TraceKey &key, TimeStamp start, TimeStamp stop) noexcept
Record a scope event described by key that started at start for the DefaultCategory.
static bool IsEnabled()
Returns whether collection of events is enabled for DefaultCategory.
Definition: collector.h:77
void RecordCounterValue(const TraceKey &key, double value)
Record a counter value for a name key if Category is enabled.
Definition: collector.h:358
static TRACE_API TraceCollector & GetInstance()
Returns the singleton instance.
Definition: collector.h:67
TimeStamp BeginEvent(const Key &key)
Record a begin event with key if Category is enabled.
Definition: collector.h:119
Holds on to a counter key, as well as the global collector for fast lookup.
Definition: trace.h:305
bool IsEnabled() const
Returns whether the TraceCollector is enabled or not.
Definition: trace.h:314
TraceCounterHolder(const TraceKey &key)
Constructor used by TRACE_COUNTER_* macro.
Definition: trace.h:309
void Record(double value, bool delta)
Records a counter delta value if the TraceCollector is enabled.
Definition: trace.h:320
This class stores data used to create dynamic keys which can be referenced in TraceEvent instances.
Definition: dynamicKey.h:25
A wrapper around a TraceStaticKeyData pointer that is stored in TraceEvent instances.
Definition: key.h:23
A class which records a timestamp when it is created and a scope event when it is destructed.
Definition: trace.h:189
TraceScopeAuto(const TraceStaticKeyData &key) noexcept
Constructor for TRACE_FUNCTION macro.
Definition: trace.h:193
~TraceScopeAuto() noexcept
Destructor.
Definition: trace.h:213
TraceScopeAuto(const TraceStaticKeyData &key, Args &&... args)
Constructor that also records scope arguments.
Definition: trace.h:201
This class holds data necessary to create keys for TraceEvent instances.
Definition: staticKeyData.h:26
ARCH_API std::string ArchGetPrettierFunctionName(const std::string &function, const std::string &prettyFunction)
Return well formatted function name.
A simple timer class for measuring an interval of time using the ArchTickTimer facilities.
Definition: timing.h:150
uint64_t GetCurrentTicks()
Read and return the current time.
Definition: timing.h:181
void Start()
Start the timer, or reset the start time if it has already been started.
Definition: timing.h:160
uint64_t GetStartTicks() const
Return this timer's start time, or 0 if it hasn't been started.
Definition: timing.h:176
bool IsStarted() const
Return true if this timer is started.
Definition: timing.h:171
A class which records a begin event when it is constructed, and a matching end event when it is destr...
Definition: trace.h:238
~TraceAuto()
Destructor.
Definition: trace.h:277
TraceAuto(const TfToken &key)
Constructor taking a TfToken key.
Definition: trace.h:252
TraceAuto(const char *funcName, const char *prettyFuncName, const std::string &name)
Constructor taking function name, pretty function name and a scope name.
Definition: trace.h:241
TraceAuto(const std::string &key)
Constructor taking a string key.
Definition: trace.h:262