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 <utility>
  13
  14 #include "mozilla/Assertions.h"
  15 #include "mozilla/Attributes.h"
  16
  17 namespace mozilla {
  18
  19 struct unused_t;
  20
  21 }  // namespace mozilla
  22
  23 /**
  24  * already_AddRefed cooperates with reference counting smart pointers to enable
  25  * you to assign in a pointer _without_ |AddRef|ing it.  You might want to use
  26  * this as a return type from a function that returns an already |AddRef|ed
  27  * pointer.
  28  *
  29  * TODO Move already_AddRefed to namespace mozilla.  This has not yet been done
  30  * because of the sheer number of usages of already_AddRefed.
  31  *
  32  * When should you use already_AddRefed<>?
  33  * * Ensure a consumer takes ownership of a reference
  34  * * Pass ownership without calling AddRef/Release (sometimes required in
  35  *   off-main-thread code)
  36  * * The ref pointer type you're using doesn't support move construction
  37  *
  38  * Otherwise, use std::move(RefPtr/nsCOMPtr/etc).
  39  */
  40 template <class T>
  41 struct
  42 #if !defined(MOZ_CLANG_PLUGIN) && !defined(XGILL_PLUGIN)
  43     [[nodiscard]]
  44 #endif
  45     MOZ_NON_AUTOABLE already_AddRefed {
  46   already_AddRefed() : mRawPtr(nullptr) {}
  47
  48   // For simplicity, allow returning nullptr from functions returning
  49   // already_AddRefed<T>. Don't permit returning raw T*, though; it's preferred
  50   // to create already_AddRefed<T> from a reference-counting smart pointer.
  51   MOZ_IMPLICIT already_AddRefed(decltype(nullptr)) : mRawPtr(nullptr) {}
  52   explicit already_AddRefed(T* aRawPtr) : mRawPtr(aRawPtr) {}
  53
  54   // Disallow copy constructor and copy assignment operator: move semantics used
  55   // instead.
  56   already_AddRefed(const already_AddRefed<T>& aOther) = delete;
  57   already_AddRefed<T>& operator=(const already_AddRefed<T>& aOther) = delete;
  58
  59   // WARNING: sketchiness ahead.
  60   //
  61   // The x86-64 ABI for Unix-like operating systems requires structures to be
  62   // returned via invisible reference if they are non-trivial for the purposes
  63   // of calls according to the C++ ABI[1].  For our consideration here, that
  64   // means that if we have a non-trivial move constructor or destructor,
  65   // already_AddRefed must be returned by invisible reference.  But
  66   // already_AddRefed is small enough and so commonly used that it would be
  67   // beneficial to return it via registers instead.  So we need to figure out
  68   // a way to make the move constructor and the destructor trivial.
  69   //
  70   // Our destructor is normally non-trivial, because it asserts that the
  71   // stored pointer has been taken by somebody else prior to destruction.
  72   // However, since the assert in question is compiled only for DEBUG builds,
  73   // we can make the destructor trivial in non-DEBUG builds by simply defining
  74   // it with `= default`.
  75   //
  76   // We now have to make the move constructor trivial as well.  It is normally
  77   // non-trivial, because the incoming object has its pointer null-ed during
  78   // the move. This null-ing is done to satisfy the assert in the destructor.
  79   // But since that destructor has no assert in non-DEBUG builds, the clearing
  80   // is unnecessary in such builds; all we really need to perform is a copy of
  81   // the pointer from the incoming object.  So we can let the compiler define
  82   // a trivial move constructor for us, and already_AddRefed can now be
  83   // returned in registers rather than needing to allocate a stack slot for
  84   // an invisible reference.
  85   //
  86   // The above considerations apply to Unix-like operating systems only; the
  87   // conditions for the same optimization to apply on x86-64 Windows are much
  88   // more strigent and are basically impossible for already_AddRefed to
  89   // satisfy[2].  But we do get some benefit from this optimization on Windows
  90   // because we removed the nulling of the pointer during the move, so that's
  91   // a codesize win.
  92   //
  93   // [1] https://itanium-cxx-abi.github.io/cxx-abi/abi.html#non-trivial
  94   // [2] https://docs.microsoft.com/en-us/cpp/build/return-values-cpp
  95
  96   already_AddRefed(already_AddRefed<T>&& aOther)
  97 #ifdef DEBUG
  98       : mRawPtr(aOther.take()){}
  99 #else
 100       = default;
 101 #endif
 102
 103         already_AddRefed<T> &
 104         operator=(already_AddRefed<T>&& aOther) {
 105     mRawPtr = aOther.take();
 106     return *this;
 107   }
 108
 109   /**
 110    * This helper is useful in cases like
 111    *
 112    *  already_AddRefed<BaseClass>
 113    *  Foo()
 114    *  {
 115    *    RefPtr<SubClass> x = ...;
 116    *    return x.forget();
 117    *  }
 118    *
 119    * The autoconversion allows one to omit the idiom
 120    *
 121    *    RefPtr<BaseClass> y = x.forget();
 122    *    return y.forget();
 123    *
 124    * Note that nsRefPtr is the XPCOM reference counting smart pointer class.
 125    */
 126   template <typename U>
 127   MOZ_IMPLICIT already_AddRefed(already_AddRefed<U>&& aOther)
 128       : mRawPtr(aOther.take()) {}
 129
 130   ~already_AddRefed()
 131 #ifdef DEBUG
 132   {
 133     MOZ_ASSERT(!mRawPtr);
 134   }
 135 #else
 136       = default;
 137 #endif
 138
 139   // Specialize the unused operator<< for already_AddRefed, to allow
 140   // nsCOMPtr<nsIFoo> foo;
 141   // Unused << foo.forget();
 142   // Note that nsCOMPtr is the XPCOM reference counting smart pointer class.
 143   friend void operator<<(const mozilla::unused_t& aUnused,
 144                          const already_AddRefed<T>& aRhs) {
 145     auto mutableAlreadyAddRefed = const_cast<already_AddRefed<T>*>(&aRhs);
 146     aUnused << mutableAlreadyAddRefed->take();
 147   }
 148
 149   [[nodiscard]] T* take() {
 150     T* rawPtr = mRawPtr;
 151     mRawPtr = nullptr;
 152     return rawPtr;
 153   }
 154
 155   /**
 156    * This helper provides a static_cast replacement for already_AddRefed, so
 157    * if you have
 158    *
 159    *   already_AddRefed<Parent> F();
 160    *
 161    * you can write
 162    *
 163    *   already_AddRefed<Child>
 164    *   G()
 165    *   {
 166    *     return F().downcast<Child>();
 167    *   }
 168    */
 169   template <class U>
 170   already_AddRefed<U> downcast() {
 171     U* tmp = static_cast<U*>(mRawPtr);
 172     mRawPtr = nullptr;
 173     return already_AddRefed<U>(tmp);
 174   }
 175
 176  private:
 177   T* MOZ_OWNING_REF mRawPtr;
 178 };
 179
 180 #endif  // AlreadyAddRefed_h