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  * The overhead of WeakPtr is that accesses to 'Foo' becomes an additional
  20  * dereference, and an additional heap allocated pointer sized object shared
  21  * between all of the WeakPtrs.
  22  *
  23  * Example of usage:
  24  *
  25  *   // To have a class C support weak pointers, inherit from
  26  *   // SupportsWeakPtr
  27  *   class C : public SupportsWeakPtr
  28  *   {
  29  *   public:
  30  *     int mNum;
  31  *     void act();
  32  *   };
  33  *
  34  *   C* ptr = new C();
  35  *
  36  *   // Get weak pointers to ptr. The first time a weak pointer
  37  *   // is obtained, a reference counted WeakReference object is created that
  38  *   // can live beyond the lifetime of 'ptr'. The WeakReference
  39  *   // object will be notified of 'ptr's destruction.
  40  *   WeakPtr<C> weak = ptr;
  41  *   WeakPtr<C> other = ptr;
  42  *
  43  *   // Test a weak pointer for validity before using it.
  44  *   if (weak) {
  45  *     weak->mNum = 17;
  46  *     weak->act();
  47  *   }
  48  *
  49  *   // Destroying the underlying object clears weak pointers to it.
  50  *   delete ptr;
  51  *
  52  *   MOZ_ASSERT(!weak, "Deleting |ptr| clears weak pointers to it.");
  53  *   MOZ_ASSERT(!other, "Deleting |ptr| clears all weak pointers to it.");
  54  *
  55  * WeakPtr is typesafe and may be used with any class. It is not required that
  56  * the class be reference-counted or allocated in any particular way.
  57  *
  58  * The API was loosely inspired by Chromium's weak_ptr.h:
  59  * http://src.chromium.org/svn/trunk/src/base/memory/weak_ptr.h
  60  *
  61  * Note that multiple base classes inheriting from SupportsWeakPtr is not
  62  * currently supported. We could support it if needed though.
  63  *
  64  * For Gecko-internal usage there is also MainThreadWeakPtr<T>, a version of
  65  * WeakPtr that can be destroyed on any thread, but whose release gets proxied
  66  * to the main thread. This is a similar API to nsMainThreadPtrHandle, but
  67  * without keeping a strong reference to the main-thread object. Said WeakPtr
  68  * can't be accessed from any other thread that isn't the main thread.
  69  */
  70
  71 #ifndef mozilla_WeakPtr_h
  72 #define mozilla_WeakPtr_h
  73
  74 #include "mozilla/ArrayUtils.h"
  75 #include "mozilla/Assertions.h"
  76 #include "mozilla/Attributes.h"
  77 #include "mozilla/Maybe.h"
  78 #include "mozilla/RefCounted.h"
  79 #include "mozilla/RefPtr.h"
  80
  81 #include <string.h>
  82 #include <type_traits>
  83
  84 #if defined(MOZILLA_INTERNAL_API)
  85 // For thread safety checking.
  86 #  include "nsISupportsImpl.h"
  87 // For main thread destructor behavior.
  88 #  include "nsProxyRelease.h"
  89 #endif
  90
  91 #if defined(MOZILLA_INTERNAL_API) && \
  92     defined(MOZ_THREAD_SAFETY_OWNERSHIP_CHECKS_SUPPORTED)
  93
  94 // Weak referencing is not implemented as thread safe.  When a WeakPtr
  95 // is created or dereferenced on thread A but the real object is just
  96 // being Released() on thread B, there is a possibility of a race
  97 // when the proxy object (detail::WeakReference) is notified about
  98 // the real object destruction just between when thread A is storing
  99 // the object pointer locally and is about to add a reference to it.
 100 //
 101 // Hence, a non-null weak proxy object is considered to have a single
 102 // "owning thread".  It means that each query for a weak reference,
 103 // its dereference, and destruction of the real object must all happen
 104 // on a single thread.  The following macros implement assertions for
 105 // checking these conditions.
 106 //
 107 // We re-use XPCOM's nsAutoOwningEventTarget checks when they are available.
 108 // This has the advantage that it works with cooperative thread pools.
 109
 110 #  define MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK \
 111     /* Will be none if mPtr = nullptr. */         \
 112     Maybe<nsAutoOwningEventTarget> _owningThread;
 113 #  define MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK() \
 114     do {                                         \
 115       if (p) {                                   \
 116         _owningThread.emplace();                 \
 117       }                                          \
 118     } while (false)
 119 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY()                  \
 120     do {                                                      \
 121       MOZ_DIAGNOSTIC_ASSERT(                                  \
 122           !_owningThread || _owningThread->IsCurrentThread(), \
 123           "WeakPtr accessed from multiple threads");          \
 124     } while (false)
 125 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(that) \
 126     (that)->AssertThreadSafety();
 127 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED_IF(that) \
 128     do {                                                      \
 129       if (that) {                                             \
 130         (that)->AssertThreadSafety();                         \
 131       }                                                       \
 132     } while (false)
 133
 134 #  define MOZ_WEAKPTR_THREAD_SAFETY_CHECKING 1
 135
 136 #else
 137
 138 #  define MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK
 139 #  define MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK() \
 140     do {                                         \
 141     } while (false)
 142 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY() \
 143     do {                                     \
 144     } while (false)
 145 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(that) \
 146     do {                                                   \
 147     } while (false)
 148 #  define MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED_IF(that) \
 149     do {                                                      \
 150     } while (false)
 151
 152 #endif
 153
 154 namespace mozilla {
 155
 156 namespace detail {
 157
 158 enum class WeakPtrDestructorBehavior {
 159   Normal,
 160 #ifdef MOZILLA_INTERNAL_API
 161   ProxyToMainThread,
 162 #endif
 163 };
 164
 165 }  // namespace detail
 166
 167 template <typename T, detail::WeakPtrDestructorBehavior =
 168                           detail::WeakPtrDestructorBehavior::Normal>
 169 class WeakPtr;
 170 class SupportsWeakPtr;
 171
 172 namespace detail {
 173
 174 // This can live beyond the lifetime of the class derived from
 175 // SupportsWeakPtr.
 176 class WeakReference : public ::mozilla::RefCounted<WeakReference> {
 177  public:
 178   explicit WeakReference(const SupportsWeakPtr* p)
 179       : mPtr(const_cast<SupportsWeakPtr*>(p)) {
 180     MOZ_WEAKPTR_INIT_THREAD_SAFETY_CHECK();
 181   }
 182
 183   SupportsWeakPtr* get() const {
 184     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY();
 185     return mPtr;
 186   }
 187
 188 #ifdef MOZ_REFCOUNTED_LEAK_CHECKING
 189   const char* typeName() const { return "WeakReference"; }
 190   size_t typeSize() const { return sizeof(*this); }
 191 #endif
 192
 193 #ifdef MOZ_WEAKPTR_THREAD_SAFETY_CHECKING
 194   void AssertThreadSafety() { MOZ_WEAKPTR_ASSERT_THREAD_SAFETY(); }
 195 #endif
 196
 197  private:
 198   friend class mozilla::SupportsWeakPtr;
 199
 200   void detach() {
 201     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY();
 202     mPtr = nullptr;
 203   }
 204
 205   SupportsWeakPtr* MOZ_NON_OWNING_REF mPtr;
 206   MOZ_WEAKPTR_DECLARE_THREAD_SAFETY_CHECK
 207 };
 208
 209 }  // namespace detail
 210
 211 class SupportsWeakPtr {
 212   using WeakReference = detail::WeakReference;
 213
 214  protected:
 215   ~SupportsWeakPtr() { DetachWeakPtr(); }
 216
 217  protected:
 218   void DetachWeakPtr() {
 219     if (mSelfReferencingWeakReference) {
 220       mSelfReferencingWeakReference->detach();
 221     }
 222   }
 223
 224  private:
 225   WeakReference* SelfReferencingWeakReference() const {
 226     if (!mSelfReferencingWeakReference) {
 227       mSelfReferencingWeakReference = new WeakReference(this);
 228     } else {
 229       MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mSelfReferencingWeakReference);
 230     }
 231     return mSelfReferencingWeakReference.get();
 232   }
 233
 234   template <typename U, detail::WeakPtrDestructorBehavior>
 235   friend class WeakPtr;
 236
 237   mutable RefPtr<WeakReference> mSelfReferencingWeakReference;
 238 };
 239
 240 template <typename T, detail::WeakPtrDestructorBehavior Destruct>
 241 class WeakPtr {
 242   using WeakReference = detail::WeakReference;
 243
 244  public:
 245   WeakPtr& operator=(const WeakPtr& aOther) {
 246     // We must make sure the reference we have now is safe to be dereferenced
 247     // before we throw it away... (this can be called from a ctor)
 248     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED_IF(mRef);
 249     // ...and make sure the new reference is used on a single thread as well.
 250     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(aOther.mRef);
 251
 252     mRef = aOther.mRef;
 253     return *this;
 254   }
 255
 256   WeakPtr(const WeakPtr& aOther) {
 257     // The thread safety check is performed inside of the operator= method.
 258     *this = aOther;
 259   }
 260
 261   WeakPtr& operator=(decltype(nullptr)) {
 262     // We must make sure the reference we have now is safe to be dereferenced
 263     // before we throw it away.
 264     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED_IF(mRef);
 265     if (!mRef || mRef->get()) {
 266       // Ensure that mRef is dereferenceable in the uninitialized state.
 267       mRef = new WeakReference(nullptr);
 268     }
 269     return *this;
 270   }
 271
 272   WeakPtr& operator=(const T* aOther) {
 273     // We must make sure the reference we have now is safe to be dereferenced
 274     // before we throw it away.
 275     MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED_IF(mRef);
 276     if (aOther) {
 277       mRef = aOther->SelfReferencingWeakReference();
 278     } else if (!mRef || mRef->get()) {
 279       // Ensure that mRef is dereferenceable in the uninitialized state.
 280       mRef = new WeakReference(nullptr);
 281     }
 282     // The thread safety check happens inside SelfReferencingWeakPtr
 283     // or is initialized in the WeakReference constructor.
 284     return *this;
 285   }
 286
 287   MOZ_IMPLICIT WeakPtr(T* aOther) {
 288     *this = aOther;
 289 #ifdef MOZILLA_INTERNAL_API
 290     if (Destruct == detail::WeakPtrDestructorBehavior::ProxyToMainThread) {
 291       MOZ_ASSERT(NS_IsMainThread(),
 292                  "MainThreadWeakPtr makes no sense on non-main threads");
 293     }
 294 #endif
 295   }
 296
 297   explicit WeakPtr(const RefPtr<T>& aOther) : WeakPtr(aOther.get()) {}
 298
 299   // Ensure that mRef is dereferenceable in the uninitialized state.
 300   WeakPtr() : mRef(new WeakReference(nullptr)) {}
 301
 302   explicit operator bool() const { return mRef->get(); }
 303   T* get() const { return static_cast<T*>(mRef->get()); }
 304   operator T*() const { return get(); }
 305   T& operator*() const { return *get(); }
 306   T* operator->() const MOZ_NO_ADDREF_RELEASE_ON_RETURN { return get(); }
 307
 308 #ifdef MOZILLA_INTERNAL_API
 309   ~WeakPtr() {
 310     if (Destruct == detail::WeakPtrDestructorBehavior::ProxyToMainThread) {
 311       NS_ReleaseOnMainThread("WeakPtr::mRef", mRef.forget());
 312     } else {
 313       MOZ_WEAKPTR_ASSERT_THREAD_SAFETY_DELEGATED(mRef);
 314     }
 315   }
 316 #endif
 317
 318  private:
 319   friend class SupportsWeakPtr;
 320
 321   explicit WeakPtr(const RefPtr<WeakReference>& aOther) : mRef(aOther) {}
 322
 323   RefPtr<WeakReference> mRef;
 324 };
 325
 326 #ifdef MOZILLA_INTERNAL_API
 327
 328 template <typename T>
 329 using MainThreadWeakPtr =
 330     WeakPtr<T, detail::WeakPtrDestructorBehavior::ProxyToMainThread>;
 331
 332 #endif
 333
 334 #define NS_IMPL_CYCLE_COLLECTION_UNLINK_WEAK_PTR tmp->DetachWeakPtr();
 335
 336 #define NS_IMPL_CYCLE_COLLECTION_WEAK_PTR(class_, ...) \
 337   NS_IMPL_CYCLE_COLLECTION_CLASS(class_)               \
 338   NS_IMPL_CYCLE_COLLECTION_UNLINK_BEGIN(class_)        \
 339     NS_IMPL_CYCLE_COLLECTION_UNLINK(__VA_ARGS__)       \
 340     NS_IMPL_CYCLE_COLLECTION_UNLINK_WEAK_PTR           \
 341   NS_IMPL_CYCLE_COLLECTION_UNLINK_END                  \
 342   NS_IMPL_CYCLE_COLLECTION_TRAVERSE_BEGIN(class_)      \
 343     NS_IMPL_CYCLE_COLLECTION_TRAVERSE(__VA_ARGS__)     \
 344   NS_IMPL_CYCLE_COLLECTION_TRAVERSE_END
 345
 346 #define NS_IMPL_CYCLE_COLLECTION_WEAK_PTR_INHERITED(class_, super_, ...) \
 347   NS_IMPL_CYCLE_COLLECTION_CLASS(class_)                                 \
 348   NS_IMPL_CYCLE_COLLECTION_UNLINK_BEGIN_INHERITED(class_, super_)        \
 349     NS_IMPL_CYCLE_COLLECTION_UNLINK(__VA_ARGS__)                         \
 350     NS_IMPL_CYCLE_COLLECTION_UNLINK_WEAK_PTR                             \
 351   NS_IMPL_CYCLE_COLLECTION_UNLINK_END                                    \
 352   NS_IMPL_CYCLE_COLLECTION_TRAVERSE_BEGIN_INHERITED(class_, super_)      \
 353     NS_IMPL_CYCLE_COLLECTION_TRAVERSE(__VA_ARGS__)                       \
 354   NS_IMPL_CYCLE_COLLECTION_TRAVERSE_END
 355
 356 }  // namespace mozilla
 357
 358 #endif /* mozilla_WeakPtr_h */