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