TfRefPtrTracker Class Reference

#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, TfHash >	OwnerTraces
	Maps a TfRefPtr address to the most recent trace for it. More...
typedef TfHashMap< const TfRefBase *, size_t, TfHash >	WatchedCounts

Public Member Functions
TF_API size_t	GetStackTraceMaxDepth () const
	Returns the maximum stack trace depth. More...
TF_API void	SetStackTraceMaxDepth (size_t)
	Sets the maximum stack trace depth. More...
TF_API WatchedCounts	GetWatchedCounts () const
TF_API OwnerTraces	GetAllTraces () const
	Returns traces for all owners. Returns a copy for thread safety. More...
TF_API void	ReportAllWatchedCounts (std::ostream &stream) const
TF_API void	ReportAllTraces (std::ostream &stream) const
	Writes all traces to stream. More...
TF_API void	ReportTracesForWatched (std::ostream &stream, const TfRefBase *watched) const
	Writes traces for all owners of watched. More...
Public Member Functions inherited from TfWeakBase
	TfWeakBase ()
	TfWeakBase (const TfWeakBase &)
const TfWeakBase &	__GetTfWeakBase__ () const
const TfWeakBase &	operator= (const TfWeakBase &)
void	EnableNotification2 () const
TF_API void const *	GetUniqueIdentifier () const

Static Public Member Functions
static TF_API TfRefPtrTracker &	GetInstance ()
static bool	WatchNone (const void *)
static bool	WatchAll (const void *)

Friends
class	Tf_RefPtrTrackerUtil
class	TfSingleton< TfRefPtrTracker >

Additional Inherited Members
Protected Member Functions inherited from TfWeakBase
	~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:

#include "pxr/base/tf/refPtrTracker.h"

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);

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.

Member Typedef Documentation

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

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

Definition at line 111 of file refPtrTracker.h.

typedef TfHashMap<const TfRefBase*, size_t, TfHash> TfRefPtrTracker::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

enum TfRefPtrTracker::TraceType

Enumerator
Add
Assign

Definition at line 83 of file refPtrTracker.h.

Member Function Documentation

TF_API OwnerTraces TfRefPtrTracker::GetAllTraces

(

)

const

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

static TF_API TfRefPtrTracker& TfRefPtrTracker::GetInstance ( )

inlinestatic

Definition at line 85 of file refPtrTracker.h.

TF_API size_t TfRefPtrTracker::GetStackTraceMaxDepth

(

)

const

Returns the maximum stack trace depth.

TF_API WatchedCounts TfRefPtrTracker::GetWatchedCounts

(

)

const

Returns the watched objects and the number of owners of each. Returns a copy for thread safety.

TF_API void TfRefPtrTracker::ReportAllTraces

(

std::ostream &

stream

)

const

Writes all traces to stream.

TF_API void TfRefPtrTracker::ReportAllWatchedCounts

(

std::ostream &

stream

)

const

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

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

Writes traces for all owners of watched.

TF_API void TfRefPtrTracker::SetStackTraceMaxDepth

(

size_t

)

Sets the maximum stack trace depth.

static bool TfRefPtrTracker::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.

static bool TfRefPtrTracker::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

friend class Tf_RefPtrTrackerUtil

friend

Definition at line 183 of file refPtrTracker.h.

friend class TfSingleton< TfRefPtrTracker >

friend

Definition at line 184 of file refPtrTracker.h.

---

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

• pxr/base/tf/refPtrTracker.h