mfbt/RefPtr.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 #ifndef mozilla_RefPtr_h
   8 #define mozilla_RefPtr_h
   9
  10 #include "mozilla/AlreadyAddRefed.h"
  11 #include "mozilla/Assertions.h"
  12 #include "mozilla/Attributes.h"
  13 #include "mozilla/DbgMacro.h"
  14
  15 /*****************************************************************************/
  16
  17 // template <class T> class RefPtrGetterAddRefs;
  18
  19 class nsQueryReferent;
  20 class nsCOMPtr_helper;
  21 class nsISupports;
  22
  23 namespace mozilla {
  24 template <class T>
  25 class OwningNonNull;
  26 template <class T>
  27 class StaticRefPtr;
  28 #if defined(XP_WIN)
  29 namespace mscom {
  30 class AgileReference;
  31 }  // namespace mscom
  32 #endif  // defined(XP_WIN)
  33
  34 // Traditionally, RefPtr supports automatic refcounting of any pointer type
  35 // with AddRef() and Release() methods that follow the traditional semantics.
  36 //
  37 // This traits class can be specialized to operate on other pointer types. For
  38 // example, we specialize this trait for opaque FFI types that represent
  39 // refcounted objects in Rust.
  40 //
  41 // Given the use of ConstRemovingRefPtrTraits below, U should not be a const-
  42 // qualified type.
  43 template <class U>
  44 struct RefPtrTraits {
  45   static void AddRef(U* aPtr) { aPtr->AddRef(); }
  46   static void Release(U* aPtr) { aPtr->Release(); }
  47 };
  48
  49 }  // namespace mozilla
  50
  51 template <class T>
  52 class MOZ_IS_REFPTR RefPtr {
  53  private:
  54   void assign_with_AddRef(T* aRawPtr) {
  55     if (aRawPtr) {
  56       ConstRemovingRefPtrTraits<T>::AddRef(aRawPtr);
  57     }
  58     assign_assuming_AddRef(aRawPtr);
  59   }
  60
  61   void assign_assuming_AddRef(T* aNewPtr) {
  62     T* oldPtr = mRawPtr;
  63     mRawPtr = aNewPtr;
  64     if (oldPtr) {
  65       ConstRemovingRefPtrTraits<T>::Release(oldPtr);
  66     }
  67   }
  68
  69  private:
  70   T* MOZ_OWNING_REF mRawPtr;
  71
  72  public:
  73   typedef T element_type;
  74
  75   ~RefPtr() {
  76     if (mRawPtr) {
  77       ConstRemovingRefPtrTraits<T>::Release(mRawPtr);
  78     }
  79   }
  80
  81   // Constructors
  82
  83   RefPtr()
  84       : mRawPtr(nullptr)
  85   // default constructor
  86   {}
  87
  88   RefPtr(const RefPtr<T>& aSmartPtr)
  89       : mRawPtr(aSmartPtr.mRawPtr)
  90   // copy-constructor
  91   {
  92     if (mRawPtr) {
  93       ConstRemovingRefPtrTraits<T>::AddRef(mRawPtr);
  94     }
  95   }
  96
  97   RefPtr(RefPtr<T>&& aRefPtr) : mRawPtr(aRefPtr.mRawPtr) {
  98     aRefPtr.mRawPtr = nullptr;
  99   }
 100
 101   // construct from a raw pointer (of the right type)
 102
 103   MOZ_IMPLICIT RefPtr(T* aRawPtr) : mRawPtr(aRawPtr) {
 104     if (mRawPtr) {
 105       ConstRemovingRefPtrTraits<T>::AddRef(mRawPtr);
 106     }
 107   }
 108
 109   MOZ_IMPLICIT RefPtr(decltype(nullptr)) : mRawPtr(nullptr) {}
 110
 111   template <typename I>
 112   MOZ_IMPLICIT RefPtr(already_AddRefed<I>& aSmartPtr)
 113       : mRawPtr(aSmartPtr.take())
 114   // construct from |already_AddRefed|
 115   {}
 116
 117   template <typename I>
 118   MOZ_IMPLICIT RefPtr(already_AddRefed<I>&& aSmartPtr)
 119       : mRawPtr(aSmartPtr.take())
 120   // construct from |otherRefPtr.forget()|
 121   {}
 122
 123   template <typename I>
 124   MOZ_IMPLICIT RefPtr(const RefPtr<I>& aSmartPtr)
 125       : mRawPtr(aSmartPtr.get())
 126   // copy-construct from a smart pointer with a related pointer type
 127   {
 128     if (mRawPtr) {
 129       ConstRemovingRefPtrTraits<T>::AddRef(mRawPtr);
 130     }
 131   }
 132
 133   template <typename I>
 134   MOZ_IMPLICIT RefPtr(RefPtr<I>&& aSmartPtr)
 135       : mRawPtr(aSmartPtr.forget().take())
 136   // construct from |Move(RefPtr<SomeSubclassOfT>)|.
 137   {}
 138
 139   MOZ_IMPLICIT RefPtr(const nsQueryReferent& aHelper);
 140   MOZ_IMPLICIT RefPtr(const nsCOMPtr_helper& aHelper);
 141 #if defined(XP_WIN)
 142   MOZ_IMPLICIT RefPtr(const mozilla::mscom::AgileReference& aAgileRef);
 143 #endif  // defined(XP_WIN)
 144
 145   // Defined in OwningNonNull.h
 146   template <class U>
 147   MOZ_IMPLICIT RefPtr(const mozilla::OwningNonNull<U>& aOther);
 148
 149   // Defined in StaticPtr.h
 150   template <class U>
 151   MOZ_IMPLICIT RefPtr(const mozilla::StaticRefPtr<U>& aOther);
 152
 153   // Assignment operators
 154
 155   RefPtr<T>& operator=(decltype(nullptr)) {
 156     assign_assuming_AddRef(nullptr);
 157     return *this;
 158   }
 159
 160   RefPtr<T>& operator=(const RefPtr<T>& aRhs)
 161   // copy assignment operator
 162   {
 163     assign_with_AddRef(aRhs.mRawPtr);
 164     return *this;
 165   }
 166
 167   template <typename I>
 168   RefPtr<T>& operator=(const RefPtr<I>& aRhs)
 169   // assign from an RefPtr of a related pointer type
 170   {
 171     assign_with_AddRef(aRhs.get());
 172     return *this;
 173   }
 174
 175   RefPtr<T>& operator=(T* aRhs)
 176   // assign from a raw pointer (of the right type)
 177   {
 178     assign_with_AddRef(aRhs);
 179     return *this;
 180   }
 181
 182   template <typename I>
 183   RefPtr<T>& operator=(already_AddRefed<I>& aRhs)
 184   // assign from |already_AddRefed|
 185   {
 186     assign_assuming_AddRef(aRhs.take());
 187     return *this;
 188   }
 189
 190   template <typename I>
 191   RefPtr<T>& operator=(already_AddRefed<I>&& aRhs)
 192   // assign from |otherRefPtr.forget()|
 193   {
 194     assign_assuming_AddRef(aRhs.take());
 195     return *this;
 196   }
 197
 198   RefPtr<T>& operator=(const nsQueryReferent& aQueryReferent);
 199   RefPtr<T>& operator=(const nsCOMPtr_helper& aHelper);
 200 #if defined(XP_WIN)
 201   RefPtr<T>& operator=(const mozilla::mscom::AgileReference& aAgileRef);
 202 #endif  // defined(XP_WIN)
 203
 204   RefPtr<T>& operator=(RefPtr<T>&& aRefPtr) {
 205     assign_assuming_AddRef(aRefPtr.forget().take());
 206     return *this;
 207   }
 208
 209   // Defined in OwningNonNull.h
 210   template <class U>
 211   RefPtr<T>& operator=(const mozilla::OwningNonNull<U>& aOther);
 212
 213   // Defined in StaticPtr.h
 214   template <class U>
 215   RefPtr<T>& operator=(const mozilla::StaticRefPtr<U>& aOther);
 216
 217   // Other pointer operators
 218
 219   void swap(RefPtr<T>& aRhs)
 220   // ...exchange ownership with |aRhs|; can save a pair of refcount operations
 221   {
 222     T* temp = aRhs.mRawPtr;
 223     aRhs.mRawPtr = mRawPtr;
 224     mRawPtr = temp;
 225   }
 226
 227   void swap(T*& aRhs)
 228   // ...exchange ownership with |aRhs|; can save a pair of refcount operations
 229   {
 230     T* temp = aRhs;
 231     aRhs = mRawPtr;
 232     mRawPtr = temp;
 233   }
 234
 235   already_AddRefed<T> MOZ_MAY_CALL_AFTER_MUST_RETURN forget()
 236   // return the value of mRawPtr and null out mRawPtr. Useful for
 237   // already_AddRefed return values.
 238   {
 239     T* temp = nullptr;
 240     swap(temp);
 241     return already_AddRefed<T>(temp);
 242   }
 243
 244   template <typename I>
 245   void forget(I** aRhs)
 246   // Set the target of aRhs to the value of mRawPtr and null out mRawPtr.
 247   // Useful to avoid unnecessary AddRef/Release pairs with "out"
 248   // parameters where aRhs bay be a T** or an I** where I is a base class
 249   // of T.
 250   {
 251     MOZ_ASSERT(aRhs, "Null pointer passed to forget!");
 252     *aRhs = mRawPtr;
 253     mRawPtr = nullptr;
 254   }
 255
 256   void forget(nsISupports** aRhs) {
 257     MOZ_ASSERT(aRhs, "Null pointer passed to forget!");
 258     *aRhs = ToSupports(mRawPtr);
 259     mRawPtr = nullptr;
 260   }
 261
 262   T* get() const
 263   /*
 264     Prefer the implicit conversion provided automatically by |operator T*()
 265     const|. Use |get()| to resolve ambiguity or to get a castable pointer.
 266   */
 267   {
 268     return const_cast<T*>(mRawPtr);
 269   }
 270
 271   operator T*() const&
 272   /*
 273     ...makes an |RefPtr| act like its underlying raw pointer type whenever it
 274     is used in a context where a raw pointer is expected.  It is this operator
 275     that makes an |RefPtr| substitutable for a raw pointer.
 276
 277     Prefer the implicit use of this operator to calling |get()|, except where
 278     necessary to resolve ambiguity.
 279   */
 280   {
 281     return get();
 282   }
 283
 284   // Don't allow implicit conversion of temporary RefPtr to raw pointer,
 285   // because the refcount might be one and the pointer will immediately become
 286   // invalid.
 287   operator T*() const&& = delete;
 288
 289   // These are needed to avoid the deleted operator above.  XXX Why is operator!
 290   // needed separately?  Shouldn't the compiler prefer using the non-deleted
 291   // operator bool instead of the deleted operator T*?
 292   explicit operator bool() const { return !!mRawPtr; }
 293   bool operator!() const { return !mRawPtr; }
 294
 295   T* operator->() const MOZ_NO_ADDREF_RELEASE_ON_RETURN {
 296     MOZ_ASSERT(mRawPtr != nullptr,
 297                "You can't dereference a NULL RefPtr with operator->().");
 298     return get();
 299   }
 300
 301   template <typename R, typename... Args>
 302   class Proxy {
 303     typedef R (T::*member_function)(Args...);
 304     T* mRawPtr;
 305     member_function mFunction;
 306
 307    public:
 308     Proxy(T* aRawPtr, member_function aFunction)
 309         : mRawPtr(aRawPtr), mFunction(aFunction) {}
 310     template <typename... ActualArgs>
 311     R operator()(ActualArgs&&... aArgs) {
 312       return ((*mRawPtr).*mFunction)(std::forward<ActualArgs>(aArgs)...);
 313     }
 314   };
 315
 316   template <typename R, typename... Args>
 317   Proxy<R, Args...> operator->*(R (T::*aFptr)(Args...)) const {
 318     MOZ_ASSERT(mRawPtr != nullptr,
 319                "You can't dereference a NULL RefPtr with operator->*().");
 320     return Proxy<R, Args...>(get(), aFptr);
 321   }
 322
 323   RefPtr<T>* get_address()
 324   // This is not intended to be used by clients.  See |address_of|
 325   // below.
 326   {
 327     return this;
 328   }
 329
 330   const RefPtr<T>* get_address() const
 331   // This is not intended to be used by clients.  See |address_of|
 332   // below.
 333   {
 334     return this;
 335   }
 336
 337  public:
 338   T& operator*() const {
 339     MOZ_ASSERT(mRawPtr != nullptr,
 340                "You can't dereference a NULL RefPtr with operator*().");
 341     return *get();
 342   }
 343
 344   T** StartAssignment() {
 345     assign_assuming_AddRef(nullptr);
 346     return reinterpret_cast<T**>(&mRawPtr);
 347   }
 348
 349  private:
 350   // This helper class makes |RefPtr<const T>| possible by casting away
 351   // the constness from the pointer when calling AddRef() and Release().
 352   //
 353   // This is necessary because AddRef() and Release() implementations can't
 354   // generally expected to be const themselves (without heavy use of |mutable|
 355   // and |const_cast| in their own implementations).
 356   //
 357   // This should be sound because while |RefPtr<const T>| provides a
 358   // const view of an object, the object itself should not be const (it
 359   // would have to be allocated as |new const T| or similar to be const).
 360   template <class U>
 361   struct ConstRemovingRefPtrTraits {
 362     static void AddRef(U* aPtr) { mozilla::RefPtrTraits<U>::AddRef(aPtr); }
 363     static void Release(U* aPtr) { mozilla::RefPtrTraits<U>::Release(aPtr); }
 364   };
 365   template <class U>
 366   struct ConstRemovingRefPtrTraits<const U> {
 367     static void AddRef(const U* aPtr) {
 368       mozilla::RefPtrTraits<U>::AddRef(const_cast<U*>(aPtr));
 369     }
 370     static void Release(const U* aPtr) {
 371       mozilla::RefPtrTraits<U>::Release(const_cast<U*>(aPtr));
 372     }
 373   };
 374 };
 375
 376 class nsCycleCollectionTraversalCallback;
 377 template <typename T>
 378 void CycleCollectionNoteChild(nsCycleCollectionTraversalCallback& aCallback,
 379                               T* aChild, const char* aName, uint32_t aFlags);
 380
 381 template <typename T>
 382 inline void ImplCycleCollectionUnlink(RefPtr<T>& aField) {
 383   aField = nullptr;
 384 }
 385
 386 template <typename T>
 387 inline void ImplCycleCollectionTraverse(
 388     nsCycleCollectionTraversalCallback& aCallback, RefPtr<T>& aField,
 389     const char* aName, uint32_t aFlags = 0) {
 390   CycleCollectionNoteChild(aCallback, aField.get(), aName, aFlags);
 391 }
 392
 393 template <class T>
 394 inline RefPtr<T>* address_of(RefPtr<T>& aPtr) {
 395   return aPtr.get_address();
 396 }
 397
 398 template <class T>
 399 inline const RefPtr<T>* address_of(const RefPtr<T>& aPtr) {
 400   return aPtr.get_address();
 401 }
 402
 403 template <class T>
 404 class RefPtrGetterAddRefs
 405 /*
 406   ...
 407
 408   This class is designed to be used for anonymous temporary objects in the
 409   argument list of calls that return COM interface pointers, e.g.,
 410
 411     RefPtr<IFoo> fooP;
 412     ...->GetAddRefedPointer(getter_AddRefs(fooP))
 413
 414   DO NOT USE THIS TYPE DIRECTLY IN YOUR CODE.  Use |getter_AddRefs()| instead.
 415
 416   When initialized with a |RefPtr|, as in the example above, it returns
 417   a |void**|, a |T**|, or an |nsISupports**| as needed, that the
 418   outer call (|GetAddRefedPointer| in this case) can fill in.
 419
 420   This type should be a nested class inside |RefPtr<T>|.
 421 */
 422 {
 423  public:
 424   explicit RefPtrGetterAddRefs(RefPtr<T>& aSmartPtr)
 425       : mTargetSmartPtr(aSmartPtr) {
 426     // nothing else to do
 427   }
 428
 429   operator void**() {
 430     return reinterpret_cast<void**>(mTargetSmartPtr.StartAssignment());
 431   }
 432
 433   operator T**() { return mTargetSmartPtr.StartAssignment(); }
 434
 435   T*& operator*() { return *(mTargetSmartPtr.StartAssignment()); }
 436
 437  private:
 438   RefPtr<T>& mTargetSmartPtr;
 439 };
 440
 441 template <class T>
 442 inline RefPtrGetterAddRefs<T> getter_AddRefs(RefPtr<T>& aSmartPtr)
 443 /*
 444   Used around a |RefPtr| when
 445   ...makes the class |RefPtrGetterAddRefs<T>| invisible.
 446 */
 447 {
 448   return RefPtrGetterAddRefs<T>(aSmartPtr);
 449 }
 450
 451 // Comparing two |RefPtr|s
 452
 453 template <class T, class U>
 454 inline bool operator==(const RefPtr<T>& aLhs, const RefPtr<U>& aRhs) {
 455   return static_cast<const T*>(aLhs.get()) == static_cast<const U*>(aRhs.get());
 456 }
 457
 458 template <class T, class U>
 459 inline bool operator!=(const RefPtr<T>& aLhs, const RefPtr<U>& aRhs) {
 460   return static_cast<const T*>(aLhs.get()) != static_cast<const U*>(aRhs.get());
 461 }
 462
 463 // Comparing an |RefPtr| to a raw pointer
 464
 465 template <class T, class U>
 466 inline bool operator==(const RefPtr<T>& aLhs, const U* aRhs) {
 467   return static_cast<const T*>(aLhs.get()) == static_cast<const U*>(aRhs);
 468 }
 469
 470 template <class T, class U>
 471 inline bool operator==(const U* aLhs, const RefPtr<T>& aRhs) {
 472   return static_cast<const U*>(aLhs) == static_cast<const T*>(aRhs.get());
 473 }
 474
 475 template <class T, class U>
 476 inline bool operator!=(const RefPtr<T>& aLhs, const U* aRhs) {
 477   return static_cast<const T*>(aLhs.get()) != static_cast<const U*>(aRhs);
 478 }
 479
 480 template <class T, class U>
 481 inline bool operator!=(const U* aLhs, const RefPtr<T>& aRhs) {
 482   return static_cast<const U*>(aLhs) != static_cast<const T*>(aRhs.get());
 483 }
 484
 485 template <class T, class U>
 486 inline bool operator==(const RefPtr<T>& aLhs, U* aRhs) {
 487   return static_cast<const T*>(aLhs.get()) == const_cast<const U*>(aRhs);
 488 }
 489
 490 template <class T, class U>
 491 inline bool operator==(U* aLhs, const RefPtr<T>& aRhs) {
 492   return const_cast<const U*>(aLhs) == static_cast<const T*>(aRhs.get());
 493 }
 494
 495 template <class T, class U>
 496 inline bool operator!=(const RefPtr<T>& aLhs, U* aRhs) {
 497   return static_cast<const T*>(aLhs.get()) != const_cast<const U*>(aRhs);
 498 }
 499
 500 template <class T, class U>
 501 inline bool operator!=(U* aLhs, const RefPtr<T>& aRhs) {
 502   return const_cast<const U*>(aLhs) != static_cast<const T*>(aRhs.get());
 503 }
 504
 505 // Comparing an |RefPtr| to |nullptr|
 506
 507 template <class T>
 508 inline bool operator==(const RefPtr<T>& aLhs, decltype(nullptr)) {
 509   return aLhs.get() == nullptr;
 510 }
 511
 512 template <class T>
 513 inline bool operator==(decltype(nullptr), const RefPtr<T>& aRhs) {
 514   return nullptr == aRhs.get();
 515 }
 516
 517 template <class T>
 518 inline bool operator!=(const RefPtr<T>& aLhs, decltype(nullptr)) {
 519   return aLhs.get() != nullptr;
 520 }
 521
 522 template <class T>
 523 inline bool operator!=(decltype(nullptr), const RefPtr<T>& aRhs) {
 524   return nullptr != aRhs.get();
 525 }
 526
 527 // MOZ_DBG support
 528
 529 template <class T>
 530 std::ostream& operator<<(std::ostream& aOut, const RefPtr<T>& aObj) {
 531   return mozilla::DebugValue(aOut, aObj.get());
 532 }
 533
 534 /*****************************************************************************/
 535
 536 template <class T>
 537 inline already_AddRefed<T> do_AddRef(T* aObj) {
 538   RefPtr<T> ref(aObj);
 539   return ref.forget();
 540 }
 541
 542 template <class T>
 543 inline already_AddRefed<T> do_AddRef(const RefPtr<T>& aObj) {
 544   RefPtr<T> ref(aObj);
 545   return ref.forget();
 546 }
 547
 548 namespace mozilla {
 549
 550 /**
 551  * Helper function to be able to conveniently write things like:
 552  *
 553  *   already_AddRefed<T>
 554  *   f(...)
 555  *   {
 556  *     return MakeAndAddRef<T>(...);
 557  *   }
 558  */
 559 template <typename T, typename... Args>
 560 already_AddRefed<T> MakeAndAddRef(Args&&... aArgs) {
 561   RefPtr<T> p(new T(std::forward<Args>(aArgs)...));
 562   return p.forget();
 563 }
 564
 565 /**
 566  * Helper function to be able to conveniently write things like:
 567  *
 568  *   auto runnable =
 569  * MakeRefPtr<ErrorCallbackRunnable<nsIDOMGetUserMediaSuccessCallback>>(
 570  *       mOnSuccess, mOnFailure, *error, mWindowID);
 571  */
 572 template <typename T, typename... Args>
 573 RefPtr<T> MakeRefPtr(Args&&... aArgs) {
 574   RefPtr<T> p(new T(std::forward<Args>(aArgs)...));
 575   return p;
 576 }
 577
 578 }  // namespace mozilla
 579
 580 #endif /* mozilla_RefPtr_h */