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