HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
refPtrTracker.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_TF_REF_PTR_TRACKER_H
25 #define PXR_BASE_TF_REF_PTR_TRACKER_H
26 
27 /// \file tf/refPtrTracker.h
28 
29 #include "pxr/pxr.h"
30 
31 #include "pxr/base/tf/api.h"
32 #include "pxr/base/tf/hash.h"
33 #include "pxr/base/tf/hashmap.h"
34 #include "pxr/base/tf/weakBase.h"
35 #include "pxr/base/tf/singleton.h"
36 #include <hboost/noncopyable.hpp>
37 #include <iosfwd>
38 #include <mutex>
39 #include <vector>
40 
42 
43 class TfRefBase;
44 template <class T> class TfRefPtr;
45 
46 /// \class TfRefPtrTracker
47 ///
48 /// Provides tracking of \c TfRefPtr objects to particular objects.
49 ///
50 /// Clients can enable, at compile time, tracking of \c TfRefPtr objects that
51 /// point to particular instances of classes derived from \c TfRefBase.
52 /// This is useful if you have a ref counted object with a ref count that
53 /// should've gone to zero but didn't. This tracker can tell you every
54 /// \c TfRefPtr that's holding the \c TfRefBase and a stack trace where it
55 /// was created or last assigned to.
56 ///
57 /// Clients can get a report of all watched instances and how many \c TfRefPtr
58 /// objects are holding them using \c ReportAllWatchedCounts() (in python use
59 /// \c Tf.RefPtrTracker().GetAllWatchedCountsReport()). You can see all of
60 /// the stack traces using \c ReportAllTraces() (in python use
61 /// \c Tf.RefPtrTracker().GetAllTracesReport()).
62 ///
63 /// Clients will typically enable tracking using code like this:
64 ///
65 /// \code
66 /// #include "pxr/base/tf/refPtrTracker.h"
67 ///
68 /// class MyRefBaseType;
69 /// typedef TfRefPtr<MyRefBaseType> MyRefBaseTypeRefPtr;
70 ///
71 /// TF_DECLARE_REFPTR_TRACK(MyRefBaseType);
72 ///
73 /// class MyRefBaseType {
74 /// ...
75 /// public:
76 /// static bool _ShouldWatch(const MyRefBaseType*);
77 /// ...
78 /// };
79 ///
80 /// TF_DEFINE_REFPTR_TRACK(MyRefBaseType, MyRefBaseType::_ShouldWatch);
81 /// \endcode
82 ///
83 /// Note that the \c TF_DECLARE_REFPTR_TRACK() macro must be invoked before
84 /// any use of the \c MyRefBaseTypeRefPtr type.
85 ///
86 /// The \c MyRefBaseType::_ShouldWatch() function returns \c true if the
87 /// given instance of \c MyRefBaseType should be tracked. You can also
88 /// use \c TfRefPtrTracker::WatchAll() to watch every instance (but that
89 /// might use a lot of memory and time).
90 ///
91 /// If you have a base type, \c B, and a derived type, \c D, and you hold
92 /// instances of \c D in a \c TfRefPtr<\c B> (i.e. a pointer to the base) then
93 /// you must track both type \c B and type \c D. But you can use
94 /// \c TfRefPtrTracker::WatchNone() when tracking \c B if you're not
95 /// interested in instances of \c B.
96 ///
97 class TfRefPtrTracker : public TfWeakBase, hboost::noncopyable {
98 public:
99  enum TraceType { Add, Assign };
100 
102  {
104  }
105 
106  /// Returns the maximum stack trace depth.
107  TF_API
108  size_t GetStackTraceMaxDepth() const;
109 
110  /// Sets the maximum stack trace depth.
111  TF_API
112  void SetStackTraceMaxDepth(size_t);
113 
114  /// A track trace.
115  struct Trace {
116  /// The stack trace when the \c TfRefPtr was created or assigned to.
117  std::vector<uintptr_t> trace;
118 
119  /// The object being pointed to.
120  const TfRefBase* obj;
121 
122  /// Whether the \c TfRefPtr was created or assigned to.
124  };
125 
126  /// Maps a \c TfRefPtr address to the most recent trace for it.
128 
129  /// Maps a \c TfRefBase object pointer to the number of \c TfRefPtr
130  /// objects using it. This should be the ref count on the \c TfRefBase
131  /// but it's tracked separately.
133 
134  /// Returns the watched objects and the number of owners of each.
135  /// Returns a copy for thread safety.
136  TF_API
138 
139  /// Returns traces for all owners. Returns a copy for thread safety.
140  TF_API
141  OwnerTraces GetAllTraces() const;
142 
143  /// Writes all watched objects and the number of owners of each
144  /// to \p stream.
145  TF_API
146  void ReportAllWatchedCounts(std::ostream& stream) const;
147 
148  /// Writes all traces to \p stream.
149  TF_API
150  void ReportAllTraces(std::ostream& stream) const;
151 
152  /// Writes traces for all owners of \p watched.
153  TF_API
154  void ReportTracesForWatched(std::ostream& stream,
155  const TfRefBase* watched) const;
156 
157  /// Handy function to pass as second argument to \c TF_DEFINE_REFPTR_TRACK.
158  /// No objects of the type will be watched but you can watch derived types.
159  /// This is important if you'll be holding TfRefPtr objects to base types;
160  /// if you don't track the base types, you'll fail to track all uses of
161  /// the derived objects.
162  static bool WatchNone(const void*)
163  {
164  return false;
165  }
166 
167  /// Handy function to pass as second argument to \c TF_DEFINE_REFPTR_TRACK.
168  /// All objects of the type will be watched.
169  static bool WatchAll(const void*)
170  {
171  return true;
172  }
173 
174 private:
175  TfRefPtrTracker();
176  ~TfRefPtrTracker();
177 
178  /// Start watching \p obj. Only watched objects are traced.
179  void _Watch(const TfRefBase* obj);
180 
181  /// Stop watching \p obj. Existing traces for \p obj are kept.
182  void _Unwatch(const TfRefBase* obj);
183 
184  /// Add a trace for a new owner \p owner of object \p obj if \p obj
185  /// is being watched.
186  void _AddTrace(const void* owner, const TfRefBase* obj, TraceType = Add);
187 
188  /// Remove traces for owner \p owner.
189  void _RemoveTraces(const void* owner);
190 
191 private:
192  typedef std::mutex _Mutex;
193  typedef std::lock_guard<std::mutex> _Lock;
194  mutable _Mutex _mutex;
195  size_t _maxDepth;
196  WatchedCounts _watched;
197  OwnerTraces _traces;
198 
199  friend class Tf_RefPtrTrackerUtil;
201 };
202 
204 
205 // For internal use only.
207 public:
208  /// Start watching \p obj. Only watched objects are traced.
209  static void Watch(const TfRefBase* obj)
210  {
211  TfRefPtrTracker::GetInstance()._Watch(obj);
212  }
213 
214  /// Stop watching \p obj. Existing traces for \p obj are kept.
215  static void Unwatch(const TfRefBase* obj)
216  {
217  TfRefPtrTracker::GetInstance()._Unwatch(obj);
218  }
219 
220  /// Add a trace for a new owner \p owner of object \p obj if \p obj
221  /// is being watched.
222  static void AddTrace(const void* owner, const TfRefBase* obj,
224  {
225  TfRefPtrTracker::GetInstance()._AddTrace(owner, obj, type);
226  }
227 
228  /// Remove traces for owner \p owner.
229  static void RemoveTraces(const void* owner)
230  {
231  TfRefPtrTracker::GetInstance()._RemoveTraces(owner);
232  }
233 };
234 
235 #define TF_DECLARE_REFPTR_TRACK(T) \
236 inline void Tf_RefPtrTracker_FirstRef(const void*, T* obj); \
237 inline void Tf_RefPtrTracker_LastRef(const void*, T* obj); \
238 inline void Tf_RefPtrTracker_New(const void* owner, T* obj); \
239 inline void Tf_RefPtrTracker_Delete(const void* owner, T* obj); \
240 inline void Tf_RefPtrTracker_Assign(const void* owner, T* obj, T* oldObj);
241 
242 #define TF_DEFINE_REFPTR_TRACK(T, COND) \
243 inline void Tf_RefPtrTracker_FirstRef(const void*, T* obj) { \
244  if (obj && COND(obj)) Tf_RefPtrTrackerUtil::Watch(obj); \
245 } \
246 inline void Tf_RefPtrTracker_LastRef(const void*, T* obj) { \
247  Tf_RefPtrTrackerUtil::Unwatch(obj); \
248 } \
249 inline void Tf_RefPtrTracker_New(const void* owner, T* obj) { \
250  Tf_RefPtrTrackerUtil::AddTrace(owner, obj); \
251 } \
252 inline void Tf_RefPtrTracker_Delete(const void* owner, T* obj) { \
253  Tf_RefPtrTrackerUtil::RemoveTraces(owner); \
254 } \
255 inline void Tf_RefPtrTracker_Assign(const void* owner, T* obj, T* oldObj) { \
256  if (oldObj != obj) { \
257  Tf_RefPtrTrackerUtil::AddTrace(owner, obj, TfRefPtrTracker::Assign);\
258  } \
259 }
260 
262 
263 #endif
TF_API void ReportTracesForWatched(std::ostream &stream, const TfRefBase *watched) const
Writes traces for all owners of watched.
static T & GetInstance()
Definition: singleton.h:137
GLuint GLuint stream
Definition: glew.h:7265
#define TF_API
Definition: api.h:40
static bool WatchNone(const void *)
static void AddTrace(const void *owner, const TfRefBase *obj, TfRefPtrTracker::TraceType type=TfRefPtrTracker::Add)
TfHashMap< const TfRefBase *, size_t, TfHash > WatchedCounts
GLhandleARB obj
Definition: glew.h:6236
TF_API_TEMPLATE_CLASS(TfSingleton< TfRefPtrTracker >)
static bool WatchAll(const void *)
TF_API void ReportAllTraces(std::ostream &stream) const
Writes all traces to stream.
TfHashMap< const void *, Trace, TfHash > OwnerTraces
Maps a TfRefPtr address to the most recent trace for it.
TraceType type
Whether the TfRefPtr was created or assigned to.
static void Unwatch(const TfRefBase *obj)
Stop watching obj. Existing traces for obj are kept.
TF_API WatchedCounts GetWatchedCounts() const
static void Watch(const TfRefBase *obj)
Start watching obj. Only watched objects are traced.
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
TF_API OwnerTraces GetAllTraces() const
Returns traces for all owners. Returns a copy for thread safety.
std::vector< uintptr_t > trace
The stack trace when the TfRefPtr was created or assigned to.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
const TfRefBase * obj
The object being pointed to.
static TF_API TfRefPtrTracker & GetInstance()
TF_API void ReportAllWatchedCounts(std::ostream &stream) const
static void RemoveTraces(const void *owner)
Remove traces for owner owner.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TF_API void SetStackTraceMaxDepth(size_t)
Sets the maximum stack trace depth.
TF_API size_t GetStackTraceMaxDepth() const
Returns the maximum stack trace depth.