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