summaryrefslogtreecommitdiffstats
path: root/mfbt/UniquePtr.h
diff options
context:
space:
mode:
Diffstat (limited to 'mfbt/UniquePtr.h')
-rw-r--r--mfbt/UniquePtr.h737
1 files changed, 737 insertions, 0 deletions
diff --git a/mfbt/UniquePtr.h b/mfbt/UniquePtr.h
new file mode 100644
index 0000000000..9b51e58db3
--- /dev/null
+++ b/mfbt/UniquePtr.h
@@ -0,0 +1,737 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ts=8 sts=2 et sw=2 tw=80: */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/* Smart pointer managing sole ownership of a resource. */
+
+#ifndef mozilla_UniquePtr_h
+#define mozilla_UniquePtr_h
+
+#include <memory>
+#include <type_traits>
+#include <utility>
+
+#include "mozilla/Assertions.h"
+#include "mozilla/Attributes.h"
+#include "mozilla/CompactPair.h"
+#include "mozilla/Compiler.h"
+
+namespace mozilla {
+
+template <typename T>
+class DefaultDelete;
+template <typename T, class D = DefaultDelete<T>>
+class UniquePtr;
+
+} // namespace mozilla
+
+namespace mozilla {
+
+namespace detail {
+
+struct HasPointerTypeHelper {
+ template <class U>
+ static double Test(...);
+ template <class U>
+ static char Test(typename U::pointer* = 0);
+};
+
+template <class T>
+class HasPointerType
+ : public std::integral_constant<bool, sizeof(HasPointerTypeHelper::Test<T>(
+ 0)) == 1> {};
+
+template <class T, class D, bool = HasPointerType<D>::value>
+struct PointerTypeImpl {
+ typedef typename D::pointer Type;
+};
+
+template <class T, class D>
+struct PointerTypeImpl<T, D, false> {
+ typedef T* Type;
+};
+
+template <class T, class D>
+struct PointerType {
+ typedef typename PointerTypeImpl<T, std::remove_reference_t<D>>::Type Type;
+};
+
+} // namespace detail
+
+/**
+ * UniquePtr is a smart pointer that wholly owns a resource. Ownership may be
+ * transferred out of a UniquePtr through explicit action, but otherwise the
+ * resource is destroyed when the UniquePtr is destroyed.
+ *
+ * UniquePtr is similar to C++98's std::auto_ptr, but it improves upon auto_ptr
+ * in one crucial way: it's impossible to copy a UniquePtr. Copying an auto_ptr
+ * obviously *can't* copy ownership of its singly-owned resource. So what
+ * happens if you try to copy one? Bizarrely, ownership is implicitly
+ * *transferred*, preserving single ownership but breaking code that assumes a
+ * copy of an object is identical to the original. (This is why auto_ptr is
+ * prohibited in STL containers.)
+ *
+ * UniquePtr solves this problem by being *movable* rather than copyable.
+ * Instead of passing a |UniquePtr u| directly to the constructor or assignment
+ * operator, you pass |Move(u)|. In doing so you indicate that you're *moving*
+ * ownership out of |u|, into the target of the construction/assignment. After
+ * the transfer completes, |u| contains |nullptr| and may be safely destroyed.
+ * This preserves single ownership but also allows UniquePtr to be moved by
+ * algorithms that have been made move-safe. (Note: if |u| is instead a
+ * temporary expression, don't use |Move()|: just pass the expression, because
+ * it's already move-ready. For more information see Move.h.)
+ *
+ * UniquePtr is also better than std::auto_ptr in that the deletion operation is
+ * customizable. An optional second template parameter specifies a class that
+ * (through its operator()(T*)) implements the desired deletion policy. If no
+ * policy is specified, mozilla::DefaultDelete<T> is used -- which will either
+ * |delete| or |delete[]| the resource, depending whether the resource is an
+ * array. Custom deletion policies ideally should be empty classes (no member
+ * fields, no member fields in base classes, no virtual methods/inheritance),
+ * because then UniquePtr can be just as efficient as a raw pointer.
+ *
+ * Use of UniquePtr proceeds like so:
+ *
+ * UniquePtr<int> g1; // initializes to nullptr
+ * g1.reset(new int); // switch resources using reset()
+ * g1 = nullptr; // clears g1, deletes the int
+ *
+ * UniquePtr<int> g2(new int); // owns that int
+ * int* p = g2.release(); // g2 leaks its int -- still requires deletion
+ * delete p; // now freed
+ *
+ * struct S { int x; S(int x) : x(x) {} };
+ * UniquePtr<S> g3, g4(new S(5));
+ * g3 = std::move(g4); // g3 owns the S, g4 cleared
+ * S* p = g3.get(); // g3 still owns |p|
+ * assert(g3->x == 5); // operator-> works (if .get() != nullptr)
+ * assert((*g3).x == 5); // also operator* (again, if not cleared)
+ * std::swap(g3, g4); // g4 now owns the S, g3 cleared
+ * g3.swap(g4); // g3 now owns the S, g4 cleared
+ * UniquePtr<S> g5(std::move(g3)); // g5 owns the S, g3 cleared
+ * g5.reset(); // deletes the S, g5 cleared
+ *
+ * struct FreePolicy { void operator()(void* p) { free(p); } };
+ * UniquePtr<int, FreePolicy> g6(static_cast<int*>(malloc(sizeof(int))));
+ * int* ptr = g6.get();
+ * g6 = nullptr; // calls free(ptr)
+ *
+ * Now, carefully note a few things you *can't* do:
+ *
+ * UniquePtr<int> b1;
+ * b1 = new int; // BAD: can only assign another UniquePtr
+ * int* ptr = b1; // BAD: no auto-conversion to pointer, use get()
+ *
+ * UniquePtr<int> b2(b1); // BAD: can't copy a UniquePtr
+ * UniquePtr<int> b3 = b1; // BAD: can't copy-assign a UniquePtr
+ *
+ * (Note that changing a UniquePtr to store a direct |new| expression is
+ * permitted, but usually you should use MakeUnique, defined at the end of this
+ * header.)
+ *
+ * A few miscellaneous notes:
+ *
+ * UniquePtr, when not instantiated for an array type, can be move-constructed
+ * and move-assigned, not only from itself but from "derived" UniquePtr<U, E>
+ * instantiations where U converts to T and E converts to D. If you want to use
+ * this, you're going to have to specify a deletion policy for both UniquePtr
+ * instantations, and T pretty much has to have a virtual destructor. In other
+ * words, this doesn't work:
+ *
+ * struct Base { virtual ~Base() {} };
+ * struct Derived : Base {};
+ *
+ * UniquePtr<Base> b1;
+ * // BAD: DefaultDelete<Base> and DefaultDelete<Derived> don't interconvert
+ * UniquePtr<Derived> d1(std::move(b));
+ *
+ * UniquePtr<Base> b2;
+ * UniquePtr<Derived, DefaultDelete<Base>> d2(std::move(b2)); // okay
+ *
+ * UniquePtr is specialized for array types. Specializing with an array type
+ * creates a smart-pointer version of that array -- not a pointer to such an
+ * array.
+ *
+ * UniquePtr<int[]> arr(new int[5]);
+ * arr[0] = 4;
+ *
+ * What else is different? Deletion of course uses |delete[]|. An operator[]
+ * is provided. Functionality that doesn't make sense for arrays is removed.
+ * The constructors and mutating methods only accept array pointers (not T*, U*
+ * that converts to T*, or UniquePtr<U[]> or UniquePtr<U>) or |nullptr|.
+ *
+ * It's perfectly okay for a function to return a UniquePtr. This transfers
+ * the UniquePtr's sole ownership of the data, to the fresh UniquePtr created
+ * in the calling function, that will then solely own that data. Such functions
+ * can return a local variable UniquePtr, |nullptr|, |UniquePtr(ptr)| where
+ * |ptr| is a |T*|, or a UniquePtr |Move()|'d from elsewhere.
+ *
+ * UniquePtr will commonly be a member of a class, with lifetime equivalent to
+ * that of that class. If you want to expose the related resource, you could
+ * expose a raw pointer via |get()|, but ownership of a raw pointer is
+ * inherently unclear. So it's better to expose a |const UniquePtr&| instead.
+ * This prohibits mutation but still allows use of |get()| when needed (but
+ * operator-> is preferred). Of course, you can only use this smart pointer as
+ * long as the enclosing class instance remains live -- no different than if you
+ * exposed the |get()| raw pointer.
+ *
+ * To pass a UniquePtr-managed resource as a pointer, use a |const UniquePtr&|
+ * argument. To specify an inout parameter (where the method may or may not
+ * take ownership of the resource, or reset it), or to specify an out parameter
+ * (where simply returning a |UniquePtr| isn't possible), use a |UniquePtr&|
+ * argument. To unconditionally transfer ownership of a UniquePtr
+ * into a method, use a |UniquePtr| argument. To conditionally transfer
+ * ownership of a resource into a method, should the method want it, use a
+ * |UniquePtr&&| argument.
+ */
+template <typename T, class D>
+class UniquePtr {
+ public:
+ typedef T ElementType;
+ typedef D DeleterType;
+ typedef typename detail::PointerType<T, DeleterType>::Type Pointer;
+
+ private:
+ mozilla::CompactPair<Pointer, DeleterType> mTuple;
+
+ Pointer& ptr() { return mTuple.first(); }
+ const Pointer& ptr() const { return mTuple.first(); }
+
+ DeleterType& del() { return mTuple.second(); }
+ const DeleterType& del() const { return mTuple.second(); }
+
+ public:
+ /**
+ * Construct a UniquePtr containing |nullptr|.
+ */
+ constexpr UniquePtr() : mTuple(static_cast<Pointer>(nullptr), DeleterType()) {
+ static_assert(!std::is_pointer_v<D>, "must provide a deleter instance");
+ static_assert(!std::is_reference_v<D>, "must provide a deleter instance");
+ }
+
+ /**
+ * Construct a UniquePtr containing |aPtr|.
+ */
+ explicit UniquePtr(Pointer aPtr) : mTuple(aPtr, DeleterType()) {
+ static_assert(!std::is_pointer_v<D>, "must provide a deleter instance");
+ static_assert(!std::is_reference_v<D>, "must provide a deleter instance");
+ }
+
+ UniquePtr(Pointer aPtr,
+ std::conditional_t<std::is_reference_v<D>, D, const D&> aD1)
+ : mTuple(aPtr, aD1) {}
+
+ UniquePtr(Pointer aPtr, std::remove_reference_t<D>&& aD2)
+ : mTuple(aPtr, std::move(aD2)) {
+ static_assert(!std::is_reference_v<D>,
+ "rvalue deleter can't be stored by reference");
+ }
+
+ UniquePtr(UniquePtr&& aOther)
+ : mTuple(aOther.release(),
+ std::forward<DeleterType>(aOther.get_deleter())) {}
+
+ MOZ_IMPLICIT constexpr UniquePtr(decltype(nullptr)) : UniquePtr() {}
+
+ template <typename U, class E>
+ MOZ_IMPLICIT UniquePtr(
+ UniquePtr<U, E>&& aOther,
+ std::enable_if_t<
+ std::is_convertible_v<typename UniquePtr<U, E>::Pointer, Pointer> &&
+ !std::is_array_v<U> &&
+ (std::is_reference_v<D> ? std::is_same_v<D, E>
+ : std::is_convertible_v<E, D>),
+ int>
+ aDummy = 0)
+ : mTuple(aOther.release(), std::forward<E>(aOther.get_deleter())) {}
+
+ ~UniquePtr() { reset(nullptr); }
+
+ UniquePtr& operator=(UniquePtr&& aOther) {
+ reset(aOther.release());
+ get_deleter() = std::forward<DeleterType>(aOther.get_deleter());
+ return *this;
+ }
+
+ template <typename U, typename E>
+ UniquePtr& operator=(UniquePtr<U, E>&& aOther) {
+ static_assert(
+ std::is_convertible_v<typename UniquePtr<U, E>::Pointer, Pointer>,
+ "incompatible UniquePtr pointees");
+ static_assert(!std::is_array_v<U>,
+ "can't assign from UniquePtr holding an array");
+
+ reset(aOther.release());
+ get_deleter() = std::forward<E>(aOther.get_deleter());
+ return *this;
+ }
+
+ UniquePtr& operator=(decltype(nullptr)) {
+ reset(nullptr);
+ return *this;
+ }
+
+ std::add_lvalue_reference_t<T> operator*() const {
+ MOZ_ASSERT(get(), "dereferencing a UniquePtr containing nullptr with *");
+ return *get();
+ }
+ Pointer operator->() const {
+ MOZ_ASSERT(get(), "dereferencing a UniquePtr containing nullptr with ->");
+ return get();
+ }
+
+ explicit operator bool() const { return get() != nullptr; }
+
+ Pointer get() const { return ptr(); }
+
+ DeleterType& get_deleter() { return del(); }
+ const DeleterType& get_deleter() const { return del(); }
+
+ [[nodiscard]] Pointer release() {
+ Pointer p = ptr();
+ ptr() = nullptr;
+ return p;
+ }
+
+ void reset(Pointer aPtr = Pointer()) {
+ Pointer old = ptr();
+ ptr() = aPtr;
+ if (old != nullptr) {
+ get_deleter()(old);
+ }
+ }
+
+ void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); }
+
+ UniquePtr(const UniquePtr& aOther) = delete; // construct using std::move()!
+ void operator=(const UniquePtr& aOther) =
+ delete; // assign using std::move()!
+};
+
+// In case you didn't read the comment by the main definition (you should!): the
+// UniquePtr<T[]> specialization exists to manage array pointers. It deletes
+// such pointers using delete[], it will reject construction and modification
+// attempts using U* or U[]. Otherwise it works like the normal UniquePtr.
+template <typename T, class D>
+class UniquePtr<T[], D> {
+ public:
+ typedef T* Pointer;
+ typedef T ElementType;
+ typedef D DeleterType;
+
+ private:
+ mozilla::CompactPair<Pointer, DeleterType> mTuple;
+
+ public:
+ /**
+ * Construct a UniquePtr containing nullptr.
+ */
+ constexpr UniquePtr() : mTuple(static_cast<Pointer>(nullptr), DeleterType()) {
+ static_assert(!std::is_pointer_v<D>, "must provide a deleter instance");
+ static_assert(!std::is_reference_v<D>, "must provide a deleter instance");
+ }
+
+ /**
+ * Construct a UniquePtr containing |aPtr|.
+ */
+ explicit UniquePtr(Pointer aPtr) : mTuple(aPtr, DeleterType()) {
+ static_assert(!std::is_pointer_v<D>, "must provide a deleter instance");
+ static_assert(!std::is_reference_v<D>, "must provide a deleter instance");
+ }
+
+ // delete[] knows how to handle *only* an array of a single class type. For
+ // delete[] to work correctly, it must know the size of each element, the
+ // fields and base classes of each element requiring destruction, and so on.
+ // So forbid all overloads which would end up invoking delete[] on a pointer
+ // of the wrong type.
+ template <typename U>
+ UniquePtr(U&& aU,
+ std::enable_if_t<
+ std::is_pointer_v<U> && std::is_convertible_v<U, Pointer>, int>
+ aDummy = 0) = delete;
+
+ UniquePtr(Pointer aPtr,
+ std::conditional_t<std::is_reference_v<D>, D, const D&> aD1)
+ : mTuple(aPtr, aD1) {}
+
+ UniquePtr(Pointer aPtr, std::remove_reference_t<D>&& aD2)
+ : mTuple(aPtr, std::move(aD2)) {
+ static_assert(!std::is_reference_v<D>,
+ "rvalue deleter can't be stored by reference");
+ }
+
+ // Forbidden for the same reasons as stated above.
+ template <typename U, typename V>
+ UniquePtr(U&& aU, V&& aV,
+ std::enable_if_t<
+ std::is_pointer_v<U> && std::is_convertible_v<U, Pointer>, int>
+ aDummy = 0) = delete;
+
+ UniquePtr(UniquePtr&& aOther)
+ : mTuple(aOther.release(),
+ std::forward<DeleterType>(aOther.get_deleter())) {}
+
+ MOZ_IMPLICIT
+ UniquePtr(decltype(nullptr)) : mTuple(nullptr, DeleterType()) {
+ static_assert(!std::is_pointer_v<D>, "must provide a deleter instance");
+ static_assert(!std::is_reference_v<D>, "must provide a deleter instance");
+ }
+
+ ~UniquePtr() { reset(nullptr); }
+
+ UniquePtr& operator=(UniquePtr&& aOther) {
+ reset(aOther.release());
+ get_deleter() = std::forward<DeleterType>(aOther.get_deleter());
+ return *this;
+ }
+
+ UniquePtr& operator=(decltype(nullptr)) {
+ reset();
+ return *this;
+ }
+
+ explicit operator bool() const { return get() != nullptr; }
+
+ T& operator[](decltype(sizeof(int)) aIndex) const { return get()[aIndex]; }
+ Pointer get() const { return mTuple.first(); }
+
+ DeleterType& get_deleter() { return mTuple.second(); }
+ const DeleterType& get_deleter() const { return mTuple.second(); }
+
+ [[nodiscard]] Pointer release() {
+ Pointer p = mTuple.first();
+ mTuple.first() = nullptr;
+ return p;
+ }
+
+ void reset(Pointer aPtr = Pointer()) {
+ Pointer old = mTuple.first();
+ mTuple.first() = aPtr;
+ if (old != nullptr) {
+ mTuple.second()(old);
+ }
+ }
+
+ void reset(decltype(nullptr)) {
+ Pointer old = mTuple.first();
+ mTuple.first() = nullptr;
+ if (old != nullptr) {
+ mTuple.second()(old);
+ }
+ }
+
+ template <typename U>
+ void reset(U) = delete;
+
+ void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); }
+
+ UniquePtr(const UniquePtr& aOther) = delete; // construct using std::move()!
+ void operator=(const UniquePtr& aOther) =
+ delete; // assign using std::move()!
+};
+
+/**
+ * A default deletion policy using plain old operator delete.
+ *
+ * Note that this type can be specialized, but authors should beware of the risk
+ * that the specialization may at some point cease to match (either because it
+ * gets moved to a different compilation unit or the signature changes). If the
+ * non-specialized (|delete|-based) version compiles for that type but does the
+ * wrong thing, bad things could happen.
+ *
+ * This is a non-issue for types which are always incomplete (i.e. opaque handle
+ * types), since |delete|-ing such a type will always trigger a compilation
+ * error.
+ */
+template <typename T>
+class DefaultDelete {
+ public:
+ constexpr DefaultDelete() = default;
+
+ template <typename U>
+ MOZ_IMPLICIT DefaultDelete(
+ const DefaultDelete<U>& aOther,
+ std::enable_if_t<std::is_convertible_v<U*, T*>, int> aDummy = 0) {}
+
+ void operator()(T* aPtr) const {
+ static_assert(sizeof(T) > 0, "T must be complete");
+ delete aPtr;
+ }
+};
+
+/** A default deletion policy using operator delete[]. */
+template <typename T>
+class DefaultDelete<T[]> {
+ public:
+ constexpr DefaultDelete() = default;
+
+ void operator()(T* aPtr) const {
+ static_assert(sizeof(T) > 0, "T must be complete");
+ delete[] aPtr;
+ }
+
+ template <typename U>
+ void operator()(U* aPtr) const = delete;
+};
+
+template <typename T, class D, typename U, class E>
+bool operator==(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY) {
+ return aX.get() == aY.get();
+}
+
+template <typename T, class D, typename U, class E>
+bool operator!=(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY) {
+ return aX.get() != aY.get();
+}
+
+template <typename T, class D>
+bool operator==(const UniquePtr<T, D>& aX, const T* aY) {
+ return aX.get() == aY;
+}
+
+template <typename T, class D>
+bool operator==(const T* aY, const UniquePtr<T, D>& aX) {
+ return aY == aX.get();
+}
+
+template <typename T, class D>
+bool operator!=(const UniquePtr<T, D>& aX, const T* aY) {
+ return aX.get() != aY;
+}
+
+template <typename T, class D>
+bool operator!=(const T* aY, const UniquePtr<T, D>& aX) {
+ return aY != aX.get();
+}
+
+template <typename T, class D>
+bool operator==(const UniquePtr<T, D>& aX, decltype(nullptr)) {
+ return !aX;
+}
+
+template <typename T, class D>
+bool operator==(decltype(nullptr), const UniquePtr<T, D>& aX) {
+ return !aX;
+}
+
+template <typename T, class D>
+bool operator!=(const UniquePtr<T, D>& aX, decltype(nullptr)) {
+ return bool(aX);
+}
+
+template <typename T, class D>
+bool operator!=(decltype(nullptr), const UniquePtr<T, D>& aX) {
+ return bool(aX);
+}
+
+// No operator<, operator>, operator<=, operator>= for now because simplicity.
+
+namespace detail {
+
+template <typename T>
+struct UniqueSelector {
+ typedef UniquePtr<T> SingleObject;
+};
+
+template <typename T>
+struct UniqueSelector<T[]> {
+ typedef UniquePtr<T[]> UnknownBound;
+};
+
+template <typename T, decltype(sizeof(int)) N>
+struct UniqueSelector<T[N]> {
+ typedef UniquePtr<T[N]> KnownBound;
+};
+
+} // namespace detail
+
+/**
+ * MakeUnique is a helper function for allocating new'd objects and arrays,
+ * returning a UniquePtr containing the resulting pointer. The semantics of
+ * MakeUnique<Type>(...) are as follows.
+ *
+ * If Type is an array T[n]:
+ * Disallowed, deleted, no overload for you!
+ * If Type is an array T[]:
+ * MakeUnique<T[]>(size_t) is the only valid overload. The pointer returned
+ * is as if by |new T[n]()|, which value-initializes each element. (If T
+ * isn't a class type, this will zero each element. If T is a class type,
+ * then roughly speaking, each element will be constructed using its default
+ * constructor. See C++11 [dcl.init]p7 for the full gory details.)
+ * If Type is non-array T:
+ * The arguments passed to MakeUnique<T>(...) are forwarded into a
+ * |new T(...)| call, initializing the T as would happen if executing
+ * |T(...)|.
+ *
+ * There are various benefits to using MakeUnique instead of |new| expressions.
+ *
+ * First, MakeUnique eliminates use of |new| from code entirely. If objects are
+ * only created through UniquePtr, then (assuming all explicit release() calls
+ * are safe, including transitively, and no type-safety casting funniness)
+ * correctly maintained ownership of the UniquePtr guarantees no leaks are
+ * possible. (This pays off best if a class is only ever created through a
+ * factory method on the class, using a private constructor.)
+ *
+ * Second, initializing a UniquePtr using a |new| expression requires repeating
+ * the name of the new'd type, whereas MakeUnique in concert with the |auto|
+ * keyword names it only once:
+ *
+ * UniquePtr<char> ptr1(new char()); // repetitive
+ * auto ptr2 = MakeUnique<char>(); // shorter
+ *
+ * Of course this assumes the reader understands the operation MakeUnique
+ * performs. In the long run this is probably a reasonable assumption. In the
+ * short run you'll have to use your judgment about what readers can be expected
+ * to know, or to quickly look up.
+ *
+ * Third, a call to MakeUnique can be assigned directly to a UniquePtr. In
+ * contrast you can't assign a pointer into a UniquePtr without using the
+ * cumbersome reset().
+ *
+ * UniquePtr<char> p;
+ * p = new char; // ERROR
+ * p.reset(new char); // works, but fugly
+ * p = MakeUnique<char>(); // preferred
+ *
+ * (And third, although not relevant to Mozilla: MakeUnique is exception-safe.
+ * An exception thrown after |new T| succeeds will leak that memory, unless the
+ * pointer is assigned to an object that will manage its ownership. UniquePtr
+ * ably serves this function.)
+ */
+
+template <typename T, typename... Args>
+typename detail::UniqueSelector<T>::SingleObject MakeUnique(Args&&... aArgs) {
+ return UniquePtr<T>(new T(std::forward<Args>(aArgs)...));
+}
+
+template <typename T>
+typename detail::UniqueSelector<T>::UnknownBound MakeUnique(
+ decltype(sizeof(int)) aN) {
+ using ArrayType = std::remove_extent_t<T>;
+ return UniquePtr<T>(new ArrayType[aN]());
+}
+
+template <typename T, typename... Args>
+typename detail::UniqueSelector<T>::KnownBound MakeUnique(Args&&... aArgs) =
+ delete;
+
+/**
+ * WrapUnique is a helper function to transfer ownership from a raw pointer
+ * into a UniquePtr<T>. It can only be used with a single non-array type.
+ *
+ * It is generally used this way:
+ *
+ * auto p = WrapUnique(new char);
+ *
+ * It can be used when MakeUnique is not usable, for example, when the
+ * constructor you are using is private, or you want to use aggregate
+ * initialization.
+ */
+
+template <typename T>
+typename detail::UniqueSelector<T>::SingleObject WrapUnique(T* aPtr) {
+ return UniquePtr<T>(aPtr);
+}
+
+} // namespace mozilla
+
+namespace std {
+
+template <typename T, class D>
+void swap(mozilla::UniquePtr<T, D>& aX, mozilla::UniquePtr<T, D>& aY) {
+ aX.swap(aY);
+}
+
+} // namespace std
+
+/**
+TempPtrToSetter(UniquePtr<T>*) -> T**-ish
+TempPtrToSetter(std::unique_ptr<T>*) -> T**-ish
+
+Make a temporary class to support assigning to UniquePtr/unique_ptr via passing
+a pointer to the callee.
+
+Often, APIs will be shaped like this trivial example:
+```
+nsresult Foo::NewChildBar(Bar** out) {
+ if (!IsOk()) return NS_ERROR_FAILURE;
+ *out = new Bar(this);
+ return NS_OK;
+}
+```
+
+In order to make this work with unique ptrs, it's often either risky or
+overwrought:
+```
+Bar* bar = nullptr;
+const auto cleanup = MakeScopeExit([&]() {
+ if (bar) {
+ delete bar;
+ }
+});
+if (FAILED(foo->NewChildBar(&bar)) {
+ // handle it
+}
+```
+
+```
+UniquePtr<Bar> bar;
+{
+ Bar* raw = nullptr;
+ const auto res = foo->NewChildBar(&bar);
+ bar.reset(raw);
+ if (FAILED(res) {
+ // handle it
+ }
+}
+```
+TempPtrToSettable is a shorthand for the latter approach, allowing something
+cleaner but also safe:
+
+```
+UniquePtr<Bar> bar;
+if (FAILED(foo->NewChildBar(TempPtrToSetter(&bar))) {
+ // handle it
+}
+```
+*/
+
+namespace mozilla {
+namespace detail {
+
+template <class T, class UniquePtrT>
+class MOZ_TEMPORARY_CLASS TempPtrToSetterT final {
+ private:
+ UniquePtrT* const mDest;
+ T* mNewVal;
+
+ public:
+ explicit TempPtrToSetterT(UniquePtrT* dest)
+ : mDest(dest), mNewVal(mDest->get()) {}
+
+ operator T**() { return &mNewVal; }
+
+ ~TempPtrToSetterT() {
+ if (mDest->get() != mNewVal) {
+ mDest->reset(mNewVal);
+ }
+ }
+};
+
+} // namespace detail
+
+template <class T, class Deleter>
+auto TempPtrToSetter(UniquePtr<T, Deleter>* const p) {
+ return detail::TempPtrToSetterT<T, UniquePtr<T, Deleter>>{p};
+}
+
+template <class T, class Deleter>
+auto TempPtrToSetter(std::unique_ptr<T, Deleter>* const p) {
+ return detail::TempPtrToSetterT<T, std::unique_ptr<T, Deleter>>{p};
+}
+
+} // namespace mozilla
+
+#endif /* mozilla_UniquePtr_h */