mfbt/WeakPtr.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* Weak pointer functionality, implemented as a mixin for use with any class. */
   8
   9 /**
  10  * SupportsWeakPtr lets you have a pointer to an object 'Foo' without affecting
  11  * its lifetime. It works by creating a single shared reference counted object
  12  * (WeakReference) that each WeakPtr will access 'Foo' through. This lets 'Foo'
  13  * clear the pointer in the WeakReference without having to know about all of
  14  * the WeakPtrs to it and allows the WeakReference to live beyond the lifetime
  15  * of 'Foo'.
  16  *
  17  * PLEASE NOTE: This weak pointer implementation is not thread-safe.
  18  *
  19  * Note that when deriving from SupportsWeakPtr you should add
  20  * MOZ_DECLARE_WEAKREFERENCE_TYPENAME(ClassName) to the public section of your
  21  * class, where ClassName is the name of your class.
  22  *
  23  * The overhead of WeakPtr is that accesses to 'Foo' becomes an additional
  24  * dereference, and an additional heap allocated pointer sized object shared
  25  * between all of the WeakPtrs.
  26  *
  27  * Example of usage:
  28  *
  29  *   // To have a class C support weak pointers, inherit from
  30  *   // SupportsWeakPtr<C>.
  31  *   class C : public SupportsWeakPtr<C>
  32  *   {
  33  *   public:
  34  *     MOZ_DECLARE_WEAKREFERENCE_TYPENAME(C)
  35  *     int mNum;
  36  *     void act();
  37  *   };
  38  *
  39  *   C* ptr = new C();
  40  *
  41  *   // Get weak pointers to ptr. The first time a weak pointer
  42  *   // is obtained, a reference counted WeakReference object is created that
  43  *   // can live beyond the lifetime of 'ptr'. The WeakReference
  44  *   // object will be notified of 'ptr's destruction.
  45  *   WeakPtr<C> weak = ptr;
  46  *   WeakPtr<C> other = ptr;
  47  *
  48  *   // Test a weak pointer for validity before using it.
  49  *   if (weak) {
  50  *     weak->mNum = 17;
  51  *     weak->act();
  52  *   }
  53  *
  54  *   // Destroying the underlying object clears weak pointers to it.
  55  *   delete ptr;
  56  *
  57  *   MOZ_ASSERT(!weak, "Deleting |ptr| clears weak pointers to it.");
  58  *   MOZ_ASSERT(!other, "Deleting |ptr| clears all weak pointers to it.");
  59  *
  60  * WeakPtr is typesafe and may be used with any class. It is not required that
  61  * the class be reference-counted or allocated in any particular way.
  62  *
  63  * The API was loosely inspired by Chromium's weak_ptr.h:
  64  * http://src.chromium.org/svn/trunk/src/base/memory/weak_ptr.h
  65  */
  66
  67 #ifndef mozilla_WeakPtr_h
  68 #define mozilla_WeakPtr_h
  69
  70 #include "mozilla/ArrayUtils.h"
  71 #include "mozilla/Assertions.h"
  72 #include "mozilla/Attributes.h"
  73 #include "mozilla/Maybe.h"
  74 #include "mozilla/RefCounted.h"
  75 #include "mozilla/RefPtr.h"
  76 #include "mozilla/TypeTraits.h"
  77
  78 #include <string.h>
  79
  80 #if defined(MOZILLA_INTERNAL_API)
  81 // For thread safety checking.
  82 #  include "nsISupportsImpl.h"
  83 #endif
  84
  85 #if defined(MOZILLA_INTERNAL_API) && \
  86     defined(MOZ_THREAD_SAFETY_OWNERSHIP_CHECKS_SUPPORTED)
  87
  88 // Weak referencing is not implemeted as thread safe.  When a WeakPtr
  89 // is created or dereferenced on thread A but the real object is just
  90 // being Released() on thread B, there is a possibility of a race
  91 // when the proxy object (detail::WeakReference) is notified about
  92 // the real object destruction just between when thread A is storing
  93 // the object pointer locally and is about to add a reference to it.
  94 //
  95 // Hence, a non-null weak proxy object is considered to have a single
  96 // "owning thread".  It means that each query for a weak reference,
  97 // its dereference, and destruction of the real object must all happen
  98 // on a single thread.  The following macros implement assertions for
  99 // checking these conditions.
 100 //
 101 // We re-use XPCOM's nsAutoOwningThread checks when they are available. This has
 102 // the advantage that it works with cooperative thread pools.
 103
 104 #  define MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK \
 105     /* Will be none if mPtr = nullptr. */         \
 106     Maybe<nsAutoOwningThread> _owningThread;
 107 #  define MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK() \
 108     do {                                         \
 109       if (p) {                                   \
 110         _owningThread.emplace();                 \
 111       }                                          \
 112     } while (false)
 113 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY()                                  \
 114     do {                                                                      \
 115       if (_owningThread.isSome() && !_owningThread.ref().IsCurrentThread()) { \
 116         WeakPtrTraits<T>::AssertSafeToAccessFromNonOwningThread();            \
 117       }                                                                       \
 118     } while (false)
 119 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(that) \
 120     (that)->AssertThreadSafety();
 121
 122 #  define MOZ_WEAKPTR_THREAD_SAFETY_CHECKING 1
 123
 124 #else
 125
 126 #  define MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK
 127 #  define MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK() \
 128     do {                                         \
 129     } while (false)
 130 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY() \
 131     do {                                     \
 132     } while (false)
 133 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(that) \
 134     do {                                                   \
 135     } while (false)
 136
 137 #endif
 138
 139 namespace mozilla {
 140
 141 template <typename T>
 142 class WeakPtr;
 143 template <typename T>
 144 class SupportsWeakPtr;
 145
 146 #ifdef MOZ_REFCOUNTED_LEAK_CHECKING
 147 #  define MOZ_DECLARE_WEAKREFERENCE_TYPENAME(T)  \
 148     static const char* weakReferenceTypeName() { \
 149       return "WeakReference<" #T ">";            \
 150     }
 151 #else
 152 #  define MOZ_DECLARE_WEAKREFERENCE_TYPENAME(T)
 153 #endif
 154
 155 template <class T>
 156 struct WeakPtrTraits {
 157   static void AssertSafeToAccessFromNonOwningThread() {
 158     MOZ_DIAGNOSTIC_ASSERT(false, "WeakPtr accessed from multiple threads");
 159   }
 160 };
 161
 162 namespace detail {
 163
 164 // This can live beyond the lifetime of the class derived from
 165 // SupportsWeakPtr.
 166 template <class T>
 167 class WeakReference : public ::mozilla::RefCounted<WeakReference<T> > {
 168  public:
 169   explicit WeakReference(T* p) : mPtr(p) {
 170     MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK();
 171   }
 172
 173   T* get() const {
 174     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY();
 175     return mPtr;
 176   }
 177
 178 #ifdef MOZ_REFCOUNTED_LEAK_CHECKING
 179   const char* typeName() const {
 180     // The first time this is called mPtr is null, so don't
 181     // invoke any methods on mPtr.
 182     return T::weakReferenceTypeName();
 183   }
 184   size_t typeSize() const { return sizeof(*this); }
 185 #endif
 186
 187 #ifdef MOZ_WEAKPTR_THREAD_SAFETY_CHECKING
 188   void AssertThreadSafety() { MOZ_WEAKPTR_ASSERT_THREAD_SAFETY(); }
 189 #endif
 190
 191  private:
 192   friend class mozilla::SupportsWeakPtr<T>;
 193
 194   void detach() {
 195     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY();
 196     mPtr = nullptr;
 197   }
 198
 199   T* MOZ_NON_OWNING_REF mPtr;
 200   MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK
 201 };
 202
 203 }  // namespace detail
 204
 205 template <typename T>
 206 class SupportsWeakPtr {
 207  protected:
 208   ~SupportsWeakPtr() {
 209     static_assert(IsBaseOf<SupportsWeakPtr<T>, T>::value,
 210                   "T must derive from SupportsWeakPtr<T>");
 211     if (mSelfReferencingWeakPtr) {
 212       mSelfReferencingWeakPtr.mRef->detach();
 213     }
 214   }
 215
 216  private:
 217   const WeakPtr<T>& SelfReferencingWeakPtr() {
 218     if (!mSelfReferencingWeakPtr) {
 219       mSelfReferencingWeakPtr.mRef =
 220           new detail::WeakReference<T>(static_cast<T*>(this));
 221     } else {
 222       MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mSelfReferencingWeakPtr.mRef);
 223     }
 224     return mSelfReferencingWeakPtr;
 225   }
 226
 227   const WeakPtr<const T>& SelfReferencingWeakPtr() const {
 228     const WeakPtr<T>& p =
 229         const_cast<SupportsWeakPtr*>(this)->SelfReferencingWeakPtr();
 230     return reinterpret_cast<const WeakPtr<const T>&>(p);
 231   }
 232
 233   friend class WeakPtr<T>;
 234   friend class WeakPtr<const T>;
 235
 236   WeakPtr<T> mSelfReferencingWeakPtr;
 237 };
 238
 239 template <typename T>
 240 class WeakPtr {
 241   typedef detail::WeakReference<T> WeakReference;
 242
 243  public:
 244   WeakPtr& operator=(const WeakPtr& aOther) {
 245     mRef = aOther.mRef;
 246     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mRef);
 247     return *this;
 248   }
 249
 250   WeakPtr(const WeakPtr& aOther) {
 251     // The thread safety check is performed inside of the operator= method.
 252     *this = aOther;
 253   }
 254
 255   WeakPtr& operator=(T* aOther) {
 256     if (aOther) {
 257       *this = aOther->SelfReferencingWeakPtr();
 258     } else if (!mRef || mRef->get()) {
 259       // Ensure that mRef is dereferenceable in the uninitialized state.
 260       mRef = new WeakReference(nullptr);
 261     }
 262     // The thread safety check happens inside SelfReferencingWeakPtr
 263     // or is initialized in the WeakReference constructor.
 264     return *this;
 265   }
 266
 267   MOZ_IMPLICIT WeakPtr(T* aOther) {
 268     *this = aOther;
 269     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mRef);
 270   }
 271
 272   // Ensure that mRef is dereferenceable in the uninitialized state.
 273   WeakPtr() : mRef(new WeakReference(nullptr)) {}
 274
 275   operator T*() const { return mRef->get(); }
 276   T& operator*() const { return *mRef->get(); }
 277
 278   T* operator->() const MOZ_NO_ADDREF_RELEASE_ON_RETURN { return mRef->get(); }
 279
 280   T* get() const { return mRef->get(); }
 281
 282   ~WeakPtr() { MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mRef); }
 283
 284  private:
 285   friend class SupportsWeakPtr<T>;
 286
 287   explicit WeakPtr(const RefPtr<WeakReference>& aOther) : mRef(aOther) {}
 288
 289   RefPtr<WeakReference> mRef;
 290 };
 291
 292 }  // namespace mozilla
 293
 294 #endif /* mozilla_WeakPtr_h */