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