TraceCollector Class Reference

This is a singleton class that records TraceEvent instances and populates TraceCollection instances. More...

+ Inheritance diagram for TraceCollector:

Classes

struct  DefaultCategory
 Default Trace category which corresponds to events stored for TRACE_ macros. More...
 

Public Types

using This = TraceCollector
 
using ThisPtr = TraceCollectorPtr
 
using TimeStamp = TraceEvent::TimeStamp
 
using Key = TraceDynamicKey
 

Public Member Functions

 TF_MALLOC_TAG_NEW ("Trace", "TraceCollector")
 
TRACE_API void SetEnabled (bool isEnabled)
 Enables or disables collection of events for DefaultCategory. More...
 
bool IsPythonTracingEnabled () const
 Returns whether automatic tracing of all python scopes is enabled. More...
 
TRACE_API void SetPythonTracingEnabled (bool enabled)
 Set whether automatic tracing of all python scopes is enabled. More...
 
TRACE_API TimeStamp GetScopeOverhead () const
 Return the overhead cost to measure a scope. More...
 
TRACE_API void Clear ()
 Clear all pending events from the collector. More...
 
const std::string & GetLabel ()
 Return the label associated with this collector. More...
 
TRACE_API void CreateCollection ()
 Produces a TraceCollection from all the events that recorded in the collector and issues a TraceCollectionAvailable notice. More...
 
- Public Member Functions inherited from TfWeakBase
 TfWeakBase (const TfWeakBase &)
 
const TfWeakBase__GetTfWeakBase__ () const
 
const TfWeakBaseoperator= (const TfWeakBase &)
 
void EnableNotification2 () const
 
TF_API void const * GetUniqueIdentifier () const
 

Static Public Member Functions

static TRACE_API TraceCollectorGetInstance ()
 Returns the singleton instance. More...
 
static bool IsEnabled ()
 Returns whether collection of events is enabled for DefaultCategory. More...
 

Friends

class TfSingleton< TraceCollector >
 

Event Recording

template<typename Category = DefaultCategory>
TimeStamp BeginEvent (const Key &key)
 Record a begin event with key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void BeginEventAtTime (const Key &key, double ms)
 Record a begin event with key at a specified time if Category is enabled. More...
 
template<typename Category = DefaultCategory>
TimeStamp EndEvent (const Key &key)
 Record an end event with key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void EndEventAtTime (const Key &key, double ms)
 Record an end event with key at a specified time if Category is enabled. More...
 
template<typename Category = DefaultCategory>
TimeStamp MarkerEvent (const Key &key)
 Record a marker event with key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void MarkerEventAtTime (const Key &key, double ms)
 Record a marker event with key at a specified time if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void BeginScope (const TraceKey &_key)
 Record a begin event for a scope described by key if Category is enabled. More...
 
template<typename Category , typename... Args>
void BeginScope (const TraceKey &key, Args &&... args)
 Record a begin event for a scope described by key and a specified category and store data arguments if Category is enabled. More...
 
template<typename... Args>
void BeginScope (const TraceKey &key, Args &&... args)
 Record a begin event for a scope described by key and store data arguments if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void EndScope (const TraceKey &key)
 Record an end event described by key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void Scope (const TraceKey &key, TimeStamp start, TimeStamp stop)
 Record a scope event described by key that started at start if Category is enabled. More...
 
template<typename Category , typename... Args>
void ScopeArgs (Args &&... args)
 Record multiple data events with category cat if Category is enabled. More...
 
template<typename... Args>
void ScopeArgs (Args &&... args)
 Record multiple data events with the default category if collection of events is enabled. More...
 
template<typename Category = DefaultCategory>
void MarkerEventStatic (const TraceKey &key)
 Record a scope event described by key that started at start if Category is enabled. More...
 
template<typename Category = DefaultCategory, typename T >
void StoreData (const TraceKey &key, const T &value)
 Record a data event with the given key and value if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void RecordCounterDelta (const TraceKey &key, double delta)
 Record a counter delta for a name key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void RecordCounterDelta (const Key &key, double delta)
 Record a counter delta for a name key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void RecordCounterValue (const TraceKey &key, double value)
 Record a counter value for a name key if Category is enabled. More...
 
template<typename Category = DefaultCategory>
void RecordCounterValue (const Key &key, double value)
 Record a counter value for a name key and delta value if Category is enabled. More...
 
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. More...
 

Additional Inherited Members

- Protected Member Functions inherited from TfWeakBase
TfRefPtr< Tf_Remnant > _Register () const
 
template<class T >
TfRefPtr< Tf_Remnant > _Register (T *tempRmnt) const
 
bool _HasRemnant () const
 

Detailed Description

This is a singleton class that records TraceEvent instances and populates TraceCollection instances.

All public methods of TraceCollector are safe to call from any thread.

Definition at line 69 of file collector.h.

Member Function Documentation

◆ BeginEvent()

TimeStamp BeginEvent ( const Key key)
inline

Record a begin event with key if Category is enabled.

A matching end event is expected some time in the future.

If the key is known at compile time BeginScope and Scope methods are preferred because they have lower overhead.

Returns
The TimeStamp of the TraceEvent or 0 if the collector is disabled.
See also
BeginScope
Scope

Definition at line 134 of file collector.h.

◆ BeginEventAtTime()

void BeginEventAtTime ( const Key key,
double  ms 
)
inline

Record a begin event with key at a specified time if Category is enabled.

This version of the method allows the passing of a specific number of elapsed milliseconds, ms, to use for this event. This method is used for testing and debugging code.

Definition at line 147 of file collector.h.

◆ BeginScope() [1/3]

void BeginScope ( const TraceKey _key)
inline

Record a begin event for a scope described by key if Category is enabled.

It is more efficient to use the Scope method than to call both BeginScope and EndScope.

See also
EndScope
Scope

Definition at line 215 of file collector.h.

◆ BeginScope() [2/3]

void BeginScope ( const TraceKey key,
Args &&...  args 
)
inline

Record a begin event for a scope described by key and a specified category and store data arguments if Category is enabled.

The variadic arguments args must be an even number of parameters in the form TraceKey, Value.

See also
EndScope
Scope
StoreData

Definition at line 228 of file collector.h.

◆ BeginScope() [3/3]

void BeginScope ( const TraceKey key,
Args &&...  args 
)
inline

Record a begin event for a scope described by key and store data arguments if Category is enabled.

The variadic arguments args must be an even number of parameters in the form TraceKey, Value.

See also
EndScope
Scope
StoreData

Definition at line 246 of file collector.h.

◆ Clear()

TRACE_API void Clear ( )

Clear all pending events from the collector.

No TraceCollection will be made for these events.

◆ CreateCollection()

TRACE_API void CreateCollection ( )

Produces a TraceCollection from all the events that recorded in the collector and issues a TraceCollectionAvailable notice.

Note that creating a collection restarts tracing, i.e. events contained in this collection will not be present in subsequent collections.

◆ EndEvent()

TimeStamp EndEvent ( const Key key)
inline

Record an end event with key if Category is enabled.

A matching begin event must have preceded this end event.

If the key is known at compile time EndScope and Scope methods are preferred because they have lower overhead.

Returns
The TimeStamp of the TraceEvent or 0 if the collector is disabled.
See also
EndScope
Scope

Definition at line 163 of file collector.h.

◆ EndEventAtTime()

void EndEventAtTime ( const Key key,
double  ms 
)
inline

Record an end event with key at a specified time if Category is enabled.

This version of the method allows the passing of a specific number of elapsed milliseconds, ms, to use for this event. This method is used for testing and debugging code.

Definition at line 176 of file collector.h.

◆ EndScope()

void EndScope ( const TraceKey key)
inline

Record an end event described by key if Category is enabled.

It is more efficient to use the Scope method than to call both BeginScope and EndScope.

See also
BeginScope
Scope

Definition at line 261 of file collector.h.

◆ GetInstance()

static TRACE_API TraceCollector& GetInstance ( )
inlinestatic

Returns the singleton instance.

Definition at line 82 of file collector.h.

◆ GetLabel()

const std::string& GetLabel ( )
inline

Return the label associated with this collector.

Definition at line 396 of file collector.h.

◆ GetScopeOverhead()

TRACE_API TimeStamp GetScopeOverhead ( ) const

Return the overhead cost to measure a scope.

◆ IsEnabled()

static bool IsEnabled ( )
inlinestatic

Returns whether collection of events is enabled for DefaultCategory.

Definition at line 92 of file collector.h.

◆ IsPythonTracingEnabled()

bool IsPythonTracingEnabled ( ) const
inline

Returns whether automatic tracing of all python scopes is enabled.

Definition at line 107 of file collector.h.

◆ MarkerEvent()

TimeStamp MarkerEvent ( const Key key)
inline

Record a marker event with key if Category is enabled.

Unlike begin/end, there is no matching event for marker events

Definition at line 189 of file collector.h.

◆ MarkerEventAtTime()

void MarkerEventAtTime ( const Key key,
double  ms 
)
inline

Record a marker event with key at a specified time if Category is enabled.

This version of the method allows the passing of a specific number of elapsed milliseconds, ms, to use for this event. This method is used for testing and debugging code.

Definition at line 202 of file collector.h.

◆ MarkerEventStatic()

void MarkerEventStatic ( const TraceKey key)
inline

Record a scope event described by key that started at start if Category is enabled.

This method is used by the TRACE_FUNCTION, TRACE_SCOPE and TRACE_FUNCTION_SCOPE macros.

See also
BeginScope
EndScope

Definition at line 330 of file collector.h.

◆ RecordCounterDelta() [1/2]

void RecordCounterDelta ( const TraceKey key,
double  delta 
)
inline

Record a counter delta for a name key if Category is enabled.

Definition at line 352 of file collector.h.

◆ RecordCounterDelta() [2/2]

void RecordCounterDelta ( const Key key,
double  delta 
)
inline

Record a counter delta for a name key if Category is enabled.

Definition at line 364 of file collector.h.

◆ RecordCounterValue() [1/2]

void RecordCounterValue ( const TraceKey key,
double  value 
)
inline

Record a counter value for a name key if Category is enabled.

Definition at line 373 of file collector.h.

◆ RecordCounterValue() [2/2]

void RecordCounterValue ( const Key key,
double  value 
)
inline

Record a counter value for a name key and delta value if Category is enabled.

Definition at line 385 of file collector.h.

◆ Scope() [1/2]

static TRACE_API void Scope ( const TraceKey key,
TimeStamp  start,
TimeStamp  stop 
)
staticnoexcept

Record a scope event described by key that started at start for the DefaultCategory.

This method is used by the TRACE_FUNCTION, TRACE_SCOPE and TRACE_FUNCTION_SCOPE macros.

See also
BeginScope
EndScope

◆ Scope() [2/2]

void Scope ( const TraceKey key,
TimeStamp  start,
TimeStamp  stop 
)
inline

Record a scope event described by key that started at start if Category is enabled.

This method is used by the TRACE_FUNCTION, TRACE_SCOPE and TRACE_FUNCTION_SCOPE macros.

See also
BeginScope
EndScope

Definition at line 285 of file collector.h.

◆ ScopeArgs() [1/2]

void ScopeArgs ( Args &&...  args)
inline

Record multiple data events with category cat if Category is enabled.

See also
StoreData

Definition at line 297 of file collector.h.

◆ ScopeArgs() [2/2]

void ScopeArgs ( Args &&...  args)
inline

Record multiple data events with the default category if collection of events is enabled.

The variadic arguments args must be an even number of parameters in the form TraceKey, Value. It is more efficient to use this method to store multiple data items than to use multiple calls to StoreData.

See also
StoreData

Definition at line 315 of file collector.h.

◆ SetEnabled()

TRACE_API void SetEnabled ( bool  isEnabled)

Enables or disables collection of events for DefaultCategory.

◆ SetPythonTracingEnabled()

TRACE_API void SetPythonTracingEnabled ( bool  enabled)

Set whether automatic tracing of all python scopes is enabled.

◆ StoreData()

void StoreData ( const TraceKey key,
const T &  value 
)
inline

Record a data event with the given key and value if Category is enabled.

value may be of any type which a TraceEvent can be constructed from (bool, int, std::string, uint64, double).

See also
ScopeArgs

Definition at line 344 of file collector.h.


The documentation for this class was generated from the following file: