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  * When should you use already_AddRefed<>?
  32  * * Ensure a consumer takes ownership of a reference
  33  * * Pass ownership without calling AddRef/Release (sometimes required in
  34  *   off-main-thread code)
  35  * * The ref pointer type you're using doesn't support move construction
  36  *
  37  * Otherwise, use Move(RefPtr/nsCOMPtr/etc).
  38  */
  39 template<class T>
  40 struct MOZ_TEMPORARY_CLASS MOZ_MUST_USE_TYPE MOZ_NON_AUTOABLE already_AddRefed
  41 {
  42   /*
  43    * We want to allow returning nullptr from functions returning
  44    * already_AddRefed<T>, for simplicity.  But we also don't want to allow
  45    * returning raw T*, instead preferring creation of already_AddRefed<T> from
  46    * a reference counting smart pointer.
  47    *
  48    * We address the latter requirement by making the (T*) constructor explicit.
  49    * But |return nullptr| won't consider an explicit constructor, so we need
  50    * another constructor to handle it.  Plain old (decltype(nullptr)) doesn't
  51    * cut it, because if nullptr is emulated as __null (with type int or long),
  52    * passing nullptr to an int/long parameter triggers compiler warnings.  We
  53    * need a type that no one can pass accidentally; a pointer-to-member-function
  54    * (where no such function exists) does the trick nicely.
  55    *
  56    * That handles the return-value case.  What about for locals, argument types,
  57    * and so on?  |already_AddRefed<T>(nullptr)| considers both overloads (and
  58    * the (already_AddRefed<T>&&) overload as well!), so there's an ambiguity.
  59    * We can target true nullptr using decltype(nullptr), but we can't target
  60    * emulated nullptr the same way, because passing __null to an int/long
  61    * parameter triggers compiler warnings.  So just give up on this, and provide
  62    * this behavior through the default constructor.
  63    *
  64    * We can revert to simply explicit (T*) and implicit (decltype(nullptr)) when
  65    * nullptr no longer needs to be emulated to support the ancient b2g compiler.
  66    * (The () overload could also be removed, if desired, if we changed callers.)
  67    */
  68   already_AddRefed() : mRawPtr(nullptr) {}
  69
  70   MOZ_IMPLICIT already_AddRefed(decltype(nullptr)) : mRawPtr(nullptr) {}
  71
  72   explicit already_AddRefed(T* aRawPtr) : mRawPtr(aRawPtr) {}
  73
  74   // Disallow copy constructor and copy assignment operator: move semantics used instead.
  75   already_AddRefed(const already_AddRefed<T>& aOther) = delete;
  76   already_AddRefed<T>& operator=(const already_AddRefed<T>& aOther) = delete;
  77
  78   // WARNING: sketchiness ahead.
  79   //
  80   // The x86-64 ABI for Unix-like operating systems requires structures to be
  81   // returned via invisible reference if they are non-trivial for the purposes
  82   // of calls according to the C++ ABI[1].  For our consideration here, that
  83   // means that if we have a non-trivial move constructor or destructor,
  84   // already_AddRefed must be returned by invisible reference.  But
  85   // already_AddRefed is small enough and so commonly used that it would be
  86   // beneficial to return it via registers instead.  So we need to figure out
  87   // a way to make the move constructor and the destructor trivial.
  88   //
  89   // Our destructor is normally non-trivial, because it asserts that the
  90   // stored pointer has been taken by somebody else prior to destruction.
  91   // However, since the assert in question is compiled only for DEBUG builds,
  92   // we can make the destructor trivial in non-DEBUG builds by simply defining
  93   // it with `= default`.
  94   //
  95   // We now have to make the move constructor trivial as well.  It is normally
  96   // non-trivial, because the incoming object has its pointer null-ed during
  97   // the move. This null-ing is done to satisfy the assert in the destructor.
  98   // But since that destructor has no assert in non-DEBUG builds, the clearing
  99   // is unnecessary in such builds; all we really need to perform is a copy of
 100   // the pointer from the incoming object.  So we can let the compiler define
 101   // a trivial move constructor for us, and already_AddRefed can now be
 102   // returned in registers rather than needing to allocate a stack slot for
 103   // an invisible reference.
 104   //
 105   // The above considerations apply to Unix-like operating systems only; the
 106   // conditions for the same optimization to apply on x86-64 Windows are much
 107   // more strigent and are basically impossible for already_AddRefed to
 108   // satisfy[2].  But we do get some benefit from this optimization on Windows
 109   // because we removed the nulling of the pointer during the move, so that's
 110   // a codesize win.
 111   //
 112   // [1] https://itanium-cxx-abi.github.io/cxx-abi/abi.html#non-trivial
 113   // [2] https://docs.microsoft.com/en-us/cpp/build/return-values-cpp
 114
 115   already_AddRefed(already_AddRefed<T>&& aOther)
 116 #ifdef DEBUG
 117     : mRawPtr(aOther.take()) {}
 118 #else
 119     = default;
 120 #endif
 121
 122   already_AddRefed<T>& operator=(already_AddRefed<T>&& aOther)
 123   {
 124     mRawPtr = aOther.take();
 125     return *this;
 126   }
 127
 128   /**
 129    * This helper is useful in cases like
 130    *
 131    *  already_AddRefed<BaseClass>
 132    *  Foo()
 133    *  {
 134    *    RefPtr<SubClass> x = ...;
 135    *    return x.forget();
 136    *  }
 137    *
 138    * The autoconversion allows one to omit the idiom
 139    *
 140    *    RefPtr<BaseClass> y = x.forget();
 141    *    return y.forget();
 142    *
 143    * Note that nsRefPtr is the XPCOM reference counting smart pointer class.
 144    */
 145   template <typename U>
 146   MOZ_IMPLICIT already_AddRefed(already_AddRefed<U>&& aOther) : mRawPtr(aOther.take()) {}
 147
 148   ~already_AddRefed()
 149 #ifdef DEBUG
 150      { MOZ_ASSERT(!mRawPtr); }
 151 #else
 152      = default;
 153 #endif
 154
 155   // Specialize the unused operator<< for already_AddRefed, to allow
 156   // nsCOMPtr<nsIFoo> foo;
 157   // Unused << foo.forget();
 158   // Note that nsCOMPtr is the XPCOM reference counting smart pointer class.
 159   friend void operator<<(const mozilla::unused_t& aUnused,
 160                          const already_AddRefed<T>& aRhs)
 161   {
 162     auto mutableAlreadyAddRefed = const_cast<already_AddRefed<T>*>(&aRhs);
 163     aUnused << mutableAlreadyAddRefed->take();
 164   }
 165
 166   MOZ_MUST_USE T* take()
 167   {
 168     T* rawPtr = mRawPtr;
 169     mRawPtr = nullptr;
 170     return rawPtr;
 171   }
 172
 173   /**
 174    * This helper provides a static_cast replacement for already_AddRefed, so
 175    * if you have
 176    *
 177    *   already_AddRefed<Parent> F();
 178    *
 179    * you can write
 180    *
 181    *   already_AddRefed<Child>
 182    *   G()
 183    *   {
 184    *     return F().downcast<Child>();
 185    *   }
 186    */
 187   template<class U>
 188   already_AddRefed<U> downcast()
 189   {
 190     U* tmp = static_cast<U*>(mRawPtr);
 191     mRawPtr = nullptr;
 192     return already_AddRefed<U>(tmp);
 193   }
 194
 195 private:
 196   T* MOZ_OWNING_REF mRawPtr;
 197 };
 198
 199 #endif // AlreadyAddRefed_h