mfbt/AlreadyAddRefed.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 /* Typed temporary pointers for reference-counted smart pointers. */
   8
   9 #ifndef AlreadyAddRefed_h
  10 #define AlreadyAddRefed_h
  11
  12 #include "mozilla/Assertions.h"
  13 #include "mozilla/Attributes.h"
  14 #include "mozilla/Move.h"
  15
  16 namespace mozilla {
  17
  18 struct unused_t;
  19
  20 } // namespace mozilla
  21
  22 /**
  23  * already_AddRefed cooperates with reference counting smart pointers to enable
  24  * you to assign in a pointer _without_ |AddRef|ing it.  You might want to use
  25  * this as a return type from a function that returns an already |AddRef|ed
  26  * pointer.
  27  *
  28  * TODO Move already_AddRefed to namespace mozilla.  This has not yet been done
  29  * because of the sheer number of usages of already_AddRefed.
  30  */
  31 template<class T>
  32 struct already_AddRefed
  33 {
  34   /*
  35    * We want to allow returning nullptr from functions returning
  36    * already_AddRefed<T>, for simplicity.  But we also don't want to allow
  37    * returning raw T*, instead preferring creation of already_AddRefed<T> from
  38    * a reference counting smart pointer.
  39    *
  40    * We address the latter requirement by making the (T*) constructor explicit.
  41    * But |return nullptr| won't consider an explicit constructor, so we need
  42    * another constructor to handle it.  Plain old (decltype(nullptr)) doesn't
  43    * cut it, because if nullptr is emulated as __null (with type int or long),
  44    * passing nullptr to an int/long parameter triggers compiler warnings.  We
  45    * need a type that no one can pass accidentally; a pointer-to-member-function
  46    * (where no such function exists) does the trick nicely.
  47    *
  48    * That handles the return-value case.  What about for locals, argument types,
  49    * and so on?  |already_AddRefed<T>(nullptr)| considers both overloads (and
  50    * the (already_AddRefed<T>&&) overload as well!), so there's an ambiguity.
  51    * We can target true nullptr using decltype(nullptr), but we can't target
  52    * emulated nullptr the same way, because passing __null to an int/long
  53    * parameter triggers compiler warnings.  So just give up on this, and provide
  54    * this behavior through the default constructor.
  55    *
  56    * We can revert to simply explicit (T*) and implicit (decltype(nullptr)) when
  57    * nullptr no longer needs to be emulated to support the ancient b2g compiler.
  58    * (The () overload could also be removed, if desired, if we changed callers.)
  59    */
  60   already_AddRefed() : mRawPtr(nullptr) {}
  61
  62   // The return and argument types here are arbitrarily selected so no
  63   // corresponding member function exists.
  64   typedef void (already_AddRefed::* MatchNullptr)(double, float);
  65   MOZ_IMPLICIT already_AddRefed(MatchNullptr aRawPtr) : mRawPtr(nullptr) {}
  66
  67   explicit already_AddRefed(T* aRawPtr) : mRawPtr(aRawPtr) {}
  68
  69   // Disallowed. Use move semantics instead.
  70   already_AddRefed(const already_AddRefed<T>& aOther) = delete;
  71
  72   already_AddRefed(already_AddRefed<T>&& aOther) : mRawPtr(aOther.take()) {}
  73
  74   ~already_AddRefed() { MOZ_ASSERT(!mRawPtr); }
  75
  76   // Specialize the unused operator<< for already_AddRefed, to allow
  77   // nsCOMPtr<nsIFoo> foo;
  78   // unused << foo.forget();
  79   // Note that nsCOMPtr is the XPCOM reference counting smart pointer class.
  80   friend void operator<<(const mozilla::unused_t& aUnused,
  81                          const already_AddRefed<T>& aRhs)
  82   {
  83     auto mutableAlreadyAddRefed = const_cast<already_AddRefed<T>*>(&aRhs);
  84     aUnused << mutableAlreadyAddRefed->take();
  85   }
  86
  87   MOZ_WARN_UNUSED_RESULT T* take()
  88   {
  89     T* rawPtr = mRawPtr;
  90     mRawPtr = nullptr;
  91     return rawPtr;
  92   }
  93
  94   /**
  95    * This helper is useful in cases like
  96    *
  97    *  already_AddRefed<BaseClass>
  98    *  Foo()
  99    *  {
 100    *    nsRefPtr<SubClass> x = ...;
 101    *    return x.forget();
 102    *  }
 103    *
 104    * The autoconversion allows one to omit the idiom
 105    *
 106    *    nsRefPtr<BaseClass> y = x.forget();
 107    *    return y.forget();
 108    *
 109    * Note that nsRefPtr is the XPCOM reference counting smart pointer class.
 110    */
 111   template<class U>
 112   operator already_AddRefed<U>()
 113   {
 114     U* tmp = mRawPtr;
 115     mRawPtr = nullptr;
 116     return already_AddRefed<U>(tmp);
 117   }
 118
 119   /**
 120    * This helper provides a static_cast replacement for already_AddRefed, so
 121    * if you have
 122    *
 123    *   already_AddRefed<Parent> F();
 124    *
 125    * you can write
 126    *
 127    *   already_AddRefed<Child>
 128    *   G()
 129    *   {
 130    *     return F().downcast<Child>();
 131    *   }
 132    */
 133   template<class U>
 134   already_AddRefed<U> downcast()
 135   {
 136     U* tmp = static_cast<U*>(mRawPtr);
 137     mRawPtr = nullptr;
 138     return already_AddRefed<U>(tmp);
 139   }
 140
 141 private:
 142   T* MOZ_OWNING_REF mRawPtr;
 143 };
 144
 145 #endif // AlreadyAddRefed_h