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
TfRefPtrTracker Class Reference

Provides tracking of TfRefPtr objects to particular objects. More...

#include <refPtrTracker.h>

+ Inheritance diagram for TfRefPtrTracker:

Classes

struct  Trace
 A track trace. More...
 

Public Types

enum  TraceType { Add , Assign }
 
typedef TfHashMap< const void *, Trace, TfHashOwnerTraces
 Maps a TfRefPtr address to the most recent trace for it.
 
typedef TfHashMap< const TfRefBase *, size_t, TfHashWatchedCounts
 Maps a TfRefBase object pointer to the number of TfRefPtr objects using it.
 

Public Member Functions

TF_API size_t GetStackTraceMaxDepth () const
 Returns the maximum stack trace depth.
 
TF_API void SetStackTraceMaxDepth (size_t)
 Sets the maximum stack trace depth.
 
TF_API WatchedCounts GetWatchedCounts () const
 Returns the watched objects and the number of owners of each.
 
TF_API OwnerTraces GetAllTraces () const
 Returns traces for all owners. Returns a copy for thread safety.
 
TF_API void ReportAllWatchedCounts (std::ostream &stream) const
 Writes all watched objects and the number of owners of each to stream.
 
TF_API void ReportAllTraces (std::ostream &stream) const
 Writes all traces to stream.
 
TF_API void ReportTracesForWatched (std::ostream &stream, const TfRefBase *watched) const
 Writes traces for all owners of watched.
 
- 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 TF_API TfRefPtrTrackerGetInstance ()
 
static bool WatchNone (const void *)
 Handy function to pass as second argument to TF_DEFINE_REFPTR_TRACK.
 
static bool WatchAll (const void *)
 Handy function to pass as second argument to TF_DEFINE_REFPTR_TRACK.
 

Friends

class TfSingleton< TfRefPtrTracker >
 

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

Provides tracking of TfRefPtr objects to particular objects.

Clients can enable, at compile time, tracking of TfRefPtr objects that point to particular instances of classes derived from TfRefBase. This is useful if you have a ref counted object with a ref count that should've gone to zero but didn't. This tracker can tell you every TfRefPtr that's holding the TfRefBase and a stack trace where it was created or last assigned to.

Clients can get a report of all watched instances and how many TfRefPtr objects are holding them using ReportAllWatchedCounts() (in python use Tf.RefPtrTracker().GetAllWatchedCountsReport()). You can see all of the stack traces using ReportAllTraces() (in python use Tf.RefPtrTracker().GetAllTracesReport()).

Clients will typically enable tracking using code like this:

class MyRefBaseType;
typedef TfRefPtr<MyRefBaseType> MyRefBaseTypeRefPtr;
TF_DECLARE_REFPTR_TRACK(MyRefBaseType);
class MyRefBaseType {
...
public:
static bool _ShouldWatch(const MyRefBaseType*);
...
};
TF_DEFINE_REFPTR_TRACK(MyRefBaseType, MyRefBaseType::_ShouldWatch);
Reference-counted smart pointer utility class.
Definition: refPtr.h:590

Note that the TF_DECLARE_REFPTR_TRACK() macro must be invoked before any use of the MyRefBaseTypeRefPtr type.

The MyRefBaseType::_ShouldWatch() function returns true if the given instance of MyRefBaseType should be tracked. You can also use TfRefPtrTracker::WatchAll() to watch every instance (but that might use a lot of memory and time).

If you have a base type, B, and a derived type, D, and you hold instances of D in a TfRefPtr<B> (i.e. a pointer to the base) then you must track both type B and type D. But you can use TfRefPtrTracker::WatchNone() when tracking B if you're not interested in instances of B.

Definition at line 79 of file refPtrTracker.h.


Class Documentation

◆ TfRefPtrTracker::Trace

struct TfRefPtrTracker::Trace

A track trace.

Definition at line 99 of file refPtrTracker.h.

Class Members
const TfRefBase * obj The object being pointed to.
vector< uintptr_t > trace The stack trace when the TfRefPtr was created or assigned to.
TraceType type Whether the TfRefPtr was created or assigned to.

Member Typedef Documentation

◆ OwnerTraces

typedef TfHashMap<const void*, Trace, TfHash> OwnerTraces

Maps a TfRefPtr address to the most recent trace for it.

Definition at line 111 of file refPtrTracker.h.

◆ WatchedCounts

typedef TfHashMap<const TfRefBase*, size_t, TfHash> WatchedCounts

Maps a TfRefBase object pointer to the number of TfRefPtr objects using it.

This should be the ref count on the TfRefBase but it's tracked separately.

Definition at line 116 of file refPtrTracker.h.

Member Enumeration Documentation

◆ TraceType

enum TraceType

Definition at line 83 of file refPtrTracker.h.

Member Function Documentation

◆ GetAllTraces()

TF_API OwnerTraces GetAllTraces ( ) const

Returns traces for all owners. Returns a copy for thread safety.

◆ GetInstance()

static TF_API TfRefPtrTracker & GetInstance ( )
inlinestatic

Definition at line 85 of file refPtrTracker.h.

◆ GetStackTraceMaxDepth()

TF_API size_t GetStackTraceMaxDepth ( ) const

Returns the maximum stack trace depth.

◆ GetWatchedCounts()

TF_API WatchedCounts GetWatchedCounts ( ) const

Returns the watched objects and the number of owners of each.

Returns a copy for thread safety.

◆ ReportAllTraces()

TF_API void ReportAllTraces ( std::ostream &  stream) const

Writes all traces to stream.

◆ ReportAllWatchedCounts()

TF_API void ReportAllWatchedCounts ( std::ostream &  stream) const

Writes all watched objects and the number of owners of each to stream.

◆ ReportTracesForWatched()

TF_API void ReportTracesForWatched ( std::ostream &  stream,
const TfRefBase watched 
) const

Writes traces for all owners of watched.

◆ SetStackTraceMaxDepth()

TF_API void SetStackTraceMaxDepth ( size_t  )

Sets the maximum stack trace depth.

◆ WatchAll()

static bool WatchAll ( const void *  )
inlinestatic

Handy function to pass as second argument to TF_DEFINE_REFPTR_TRACK.

All objects of the type will be watched.

Definition at line 153 of file refPtrTracker.h.

◆ WatchNone()

static bool WatchNone ( const void *  )
inlinestatic

Handy function to pass as second argument to TF_DEFINE_REFPTR_TRACK.

No objects of the type will be watched but you can watch derived types. This is important if you'll be holding TfRefPtr objects to base types; if you don't track the base types, you'll fail to track all uses of the derived objects.

Definition at line 146 of file refPtrTracker.h.

Friends And Related Function Documentation

◆ TfSingleton< TfRefPtrTracker >

friend class TfSingleton< TfRefPtrTracker >
friend

Definition at line 183 of file refPtrTracker.h.


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