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 File Reference
+ Include dependency graph for trace.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  TraceScopeAuto
 A class which records a timestamp when it is created and a scope event when it is destructed. More...
 
class  TraceAuto
 A class which records a begin event when it is constructed, and a matching end event when it is destructed. More...
 
class  TraceCounterHolder
 Holds on to a counter key, as well as the global collector for fast lookup. More...
 

Macros

#define TRACE_FUNCTION()    _TRACE_FUNCTION_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__)
 Records a timestamp when constructed and a timespan event when destructed, using the name of the function or method as the key.
 
#define TRACE_SCOPE(name)    _TRACE_SCOPE_INSTANCE(__LINE__, name)
 Records a timestamp when constructed and a timespan event when destructed, using name as the key.
 
#define TRACE_FUNCTION_SCOPE(name)
 Records a timestamp when constructed and a timespan event when destructed, using the name of the function concatenated with name as the key.
 
#define TRACE_MARKER(name)    _TRACE_MARKER_INSTANCE(__LINE__, name)
 Records a timestamp when constructed, using name as the key.
 
#define TRACE_MARKER_DYNAMIC(name)    _TRACE_MARKER_DYNAMIC_INSTANCE(__LINE__, name)
 Records a timestamp when constructed, using name as the key.
 
#define TRACE_COUNTER_DELTA(name, delta)    _TRACE_COUNTER_INSTANCE(__LINE__, name, delta, /* isDelta */ true)
 Records a counter delta using the name as the counter key.
 
#define TRACE_COUNTER_DELTA_DYNAMIC(name, delta)    TraceCollector::GetInstance().RecordCounterDelta(name, delta);
 Records a counter delta using the name as the counter key.
 
#define TRACE_COUNTER_VALUE(name, value)    _TRACE_COUNTER_INSTANCE(__LINE__, name, value, /* isDelta */ false)
 Records a counter value using the name as the counter key.
 
#define TRACE_COUNTER_VALUE_DYNAMIC(name, value)    TraceCollector::GetInstance().RecordCounterValue(name, value);
 Records a counter value using the name as the counter key.
 
#define TRACE_COUNTER_DELTA_CODE(name, code)    _TRACE_COUNTER_CODE_INSTANCE(__LINE__, name, code, true)
 Records a counter value using the name as the counter key.
 
#define TRACE_FUNCTION_DYNAMIC(name)    _TRACE_FUNCTION_DYNAMIC_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__, name)
 Records a begin event when constructed and an end event when destructed, using name of the function or method and the supplied name as the key.
 
#define TRACE_SCOPE_DYNAMIC(name)    _TRACE_SCOPE_DYNAMIC_INSTANCE(__LINE__, name)
 Records a begin event when constructed and an end event when destructed, using name as the key.
 
#define _TRACE_FUNCTION_INSTANCE(instance, name, prettyName)
 These pair a uniquely named TraceScopeHolder with a TraceScopeAuto.
 
#define _TRACE_SCOPE_INSTANCE(instance, name)
 
#define _TRACE_FUNCTION_SCOPE_INSTANCE(instance, name, prettyName, scopeName)
 
#define _TRACE_MARKER_INSTANCE(instance, name)
 
#define _TRACE_COUNTER_INSTANCE(instance, name, value, isDelta)
 
#define _TRACE_COUNTER_CODE_INSTANCE(instance, name, code, isDelta)
 
#define _TRACE_FUNCTION_DYNAMIC_INSTANCE(instance, fnName, fnPrettyName, name)   PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(fnName, fnPrettyName, name)
 
#define _TRACE_SCOPE_DYNAMIC_INSTANCE(instance, str)   PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(str)
 
#define _TRACE_MARKER_DYNAMIC_INSTANCE(instance, name)    TraceCollector::GetInstance().MarkerEvent(name);
 

Macro Definition Documentation

◆ _TRACE_COUNTER_CODE_INSTANCE

#define _TRACE_COUNTER_CODE_INSTANCE (   instance,
  name,
  code,
  isDelta 
)
Value:
static PXR_NS::TraceCounterHolder \
TF_PP_CAT(TraceCounterHolder_, instance)(name); \
if (TF_PP_CAT(TraceCounterHolder_, instance).IsEnabled()) { \
double value = 0.0; \
code \
TF_PP_CAT(TraceCounterHolder_, instance).RecordDelta(value, isDelta); \
}

Definition at line 151 of file trace.h.

◆ _TRACE_COUNTER_INSTANCE

#define _TRACE_COUNTER_INSTANCE (   instance,
  name,
  value,
  isDelta 
)
Value:
constexpr static PXR_NS::TraceStaticKeyData \
TF_PP_CAT(TraceKeyData_, instance)(name); \
static PXR_NS::TraceCounterHolder \
TF_PP_CAT(TraceCounterHolder_, instance) \
(TF_PP_CAT(TraceKeyData_, instance)); \
TF_PP_CAT(TraceCounterHolder_, instance).Record(value, isDelta);

Definition at line 143 of file trace.h.

◆ _TRACE_FUNCTION_DYNAMIC_INSTANCE

#define _TRACE_FUNCTION_DYNAMIC_INSTANCE (   instance,
  fnName,
  fnPrettyName,
  name 
)    PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(fnName, fnPrettyName, name)

Definition at line 160 of file trace.h.

◆ _TRACE_FUNCTION_INSTANCE

#define _TRACE_FUNCTION_INSTANCE (   instance,
  name,
  prettyName 
)
Value:
constexpr static PXR_NS::TraceStaticKeyData \
TF_PP_CAT(TraceKeyData_, instance)(name, prettyName); \
PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
TF_PP_CAT(TraceKeyData_, instance));

These pair a uniquely named TraceScopeHolder with a TraceScopeAuto.

Together these will register a TraceScope only the first time the code is executed or if the TraceScope expires. Otherwise, the held TraceScope will be used to record begin and end events.

Definition at line 120 of file trace.h.

◆ _TRACE_FUNCTION_SCOPE_INSTANCE

#define _TRACE_FUNCTION_SCOPE_INSTANCE (   instance,
  name,
  prettyName,
  scopeName 
)
Value:
constexpr static PXR_NS::TraceStaticKeyData \
TF_PP_CAT(TraceKeyData_, instance)(name, prettyName, scopeName); \
PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
TF_PP_CAT(TraceKeyData_, instance));

Definition at line 132 of file trace.h.

◆ _TRACE_MARKER_DYNAMIC_INSTANCE

#define _TRACE_MARKER_DYNAMIC_INSTANCE (   instance,
  name 
)     TraceCollector::GetInstance().MarkerEvent(name);

Definition at line 166 of file trace.h.

◆ _TRACE_MARKER_INSTANCE

#define _TRACE_MARKER_INSTANCE (   instance,
  name 
)
Value:
constexpr static PXR_NS::TraceStaticKeyData \
TF_PP_CAT(TraceKeyData_, instance)(name); \
TraceCollector::GetInstance().MarkerEventStatic(TF_PP_CAT(TraceKeyData_, instance));

Definition at line 138 of file trace.h.

◆ _TRACE_SCOPE_DYNAMIC_INSTANCE

#define _TRACE_SCOPE_DYNAMIC_INSTANCE (   instance,
  str 
)    PXR_NS::TraceAuto TF_PP_CAT(TraceAuto_, instance)(str)

Definition at line 163 of file trace.h.

◆ _TRACE_SCOPE_INSTANCE

#define _TRACE_SCOPE_INSTANCE (   instance,
  name 
)
Value:
constexpr static PXR_NS::TraceStaticKeyData \
TF_PP_CAT(TraceKeyData_, instance)(name); \
PXR_NS::TraceScopeAuto TF_PP_CAT(TraceScopeAuto_, instance)(\
TF_PP_CAT(TraceKeyData_, instance));

Definition at line 126 of file trace.h.

◆ TRACE_COUNTER_DELTA

#define TRACE_COUNTER_DELTA (   name,
  delta 
)     _TRACE_COUNTER_INSTANCE(__LINE__, name, delta, /* isDelta */ true)

Records a counter delta using the name as the counter key.

The delta can be positive or negative. A positive delta will increment the total counter value, whereas a negative delta will decrement it. The recorded value will be stored at the currently traced scope, and will propagate up to the parent scopes.

Definition at line 53 of file trace.h.

◆ TRACE_COUNTER_DELTA_CODE

#define TRACE_COUNTER_DELTA_CODE (   name,
  code 
)     _TRACE_COUNTER_CODE_INSTANCE(__LINE__, name, code, true)

Records a counter value using the name as the counter key.

The value can be positive or negative. A positive value will increment the total counter value, whereas a negative value will decrement it. The recorded value will be stored at the currently traced scope, and will propagate up to the parent scopes.

This macro provides the same functionality as TRACE_COUNTER_DELTA, but takes a section of code in brackets, which assumes that a value will be assigned to 'value'. The section of code will not be executed, when tracing is turned off, which makes it possible to gather counter values from potentially expensive logic, without incurring an overhead with tracing turned off.

Usage:

TRACE_COUNTER_DELTA_CODE("My counter", { value = _ComputeExpensiveCounterValue(); })

Definition at line 94 of file trace.h.

◆ TRACE_COUNTER_DELTA_DYNAMIC

#define TRACE_COUNTER_DELTA_DYNAMIC (   name,
  delta 
)     TraceCollector::GetInstance().RecordCounterDelta(name, delta);

Records a counter delta using the name as the counter key.

Similar to TRACE_COUNTER_DELTA except that name does not need to be a compile time string.

See also
TRACE_COUNTER_DELTA

Definition at line 60 of file trace.h.

◆ TRACE_COUNTER_VALUE

#define TRACE_COUNTER_VALUE (   name,
  value 
)     _TRACE_COUNTER_INSTANCE(__LINE__, name, value, /* isDelta */ false)

Records a counter value using the name as the counter key.

The recorded value will be stored at the currently traced scope, and will propagate up to the parent scopes.

Definition at line 66 of file trace.h.

◆ TRACE_COUNTER_VALUE_DYNAMIC

#define TRACE_COUNTER_VALUE_DYNAMIC (   name,
  value 
)     TraceCollector::GetInstance().RecordCounterValue(name, value);

Records a counter value using the name as the counter key.

Similar to TRACE_COUNTER_VALUE except that name does not need to be a compile time string.

See also
TRACE_COUNTER_VALUE

Definition at line 73 of file trace.h.

◆ TRACE_FUNCTION

#define TRACE_FUNCTION ( )     _TRACE_FUNCTION_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__)

Records a timestamp when constructed and a timespan event when destructed, using the name of the function or method as the key.

Definition at line 26 of file trace.h.

◆ TRACE_FUNCTION_DYNAMIC

#define TRACE_FUNCTION_DYNAMIC (   name)     _TRACE_FUNCTION_DYNAMIC_INSTANCE(__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__, name)

Records a begin event when constructed and an end event when destructed, using name of the function or method and the supplied name as the key.

Unlike TRACE_FUNCTION, the name argument will be evaluated each time this macro is invoked. This allows for a single TRACE_FUNCTION to track time under different keys, but incurs greater overhead.

Definition at line 102 of file trace.h.

◆ TRACE_FUNCTION_SCOPE

#define TRACE_FUNCTION_SCOPE (   name)
Value:
_TRACE_FUNCTION_SCOPE_INSTANCE( \
__LINE__, __ARCH_FUNCTION__, __ARCH_PRETTY_FUNCTION__, name)

Records a timestamp when constructed and a timespan event when destructed, using the name of the function concatenated with name as the key.

Definition at line 36 of file trace.h.

◆ TRACE_MARKER

#define TRACE_MARKER (   name)     _TRACE_MARKER_INSTANCE(__LINE__, name)

Records a timestamp when constructed, using name as the key.

Definition at line 41 of file trace.h.

◆ TRACE_MARKER_DYNAMIC

#define TRACE_MARKER_DYNAMIC (   name)     _TRACE_MARKER_DYNAMIC_INSTANCE(__LINE__, name)

Records a timestamp when constructed, using name as the key.

Definition at line 45 of file trace.h.

◆ TRACE_SCOPE

#define TRACE_SCOPE (   name)     _TRACE_SCOPE_INSTANCE(__LINE__, name)

Records a timestamp when constructed and a timespan event when destructed, using name as the key.

Definition at line 31 of file trace.h.

◆ TRACE_SCOPE_DYNAMIC

#define TRACE_SCOPE_DYNAMIC (   name)     _TRACE_SCOPE_DYNAMIC_INSTANCE(__LINE__, name)

Records a begin event when constructed and an end event when destructed, using name as the key.

Unlike TRACE_SCOPE, the name argument will be evaluated each time this macro is invoked. This allows for a single TRACE_SCOPE to track time under different keys, but incurs greater overhead.

Definition at line 110 of file trace.h.