/* -*- 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 "mozilla/Assertions.h" #include "mozilla/Attributes.h" #include "mozilla/Compiler.h" #include "mozilla/Move.h" #include "mozilla/NullPtr.h" #include "mozilla/Pair.h" #include "mozilla/TypeTraits.h" namespace mozilla { template class DefaultDelete; template> class UniquePtr; } // namespace mozilla namespace mozilla { /** * 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 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 g1; // initializes to nullptr * g1.reset(new int); // switch resources using reset() * g1 = nullptr; // clears g1, deletes the int * * UniquePtr 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 g3, g4(new S(5)); * g3 = 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) * Swap(g3, g4); // g4 now owns the S, g3 cleared * g3.swap(g4); // g3 now owns the S, g4 cleared * UniquePtr g5(Move(g3)); // g5 owns the S, g3 cleared * g5.reset(); // deletes the S, g5 cleared * * struct FreePolicy { void operator()(void* p) { free(p); } }; * UniquePtr g6(static_cast(malloc(sizeof(int)))); * int* ptr = g6.get(); * g6 = nullptr; // calls free(ptr) * * Now, carefully note a few things you *can't* do: * * UniquePtr b1; * b1 = new int; // BAD: can only assign another UniquePtr * int* ptr = b1; // BAD: no auto-conversion to pointer, use get() * * UniquePtr b2(b1); // BAD: can't copy a UniquePtr * UniquePtr 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 * 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 b1; * // BAD: DefaultDelete and DefaultDelete don't interconvert * UniquePtr d1(Move(b)); * * UniquePtr b2; * UniquePtr> d2(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 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 or UniquePtr) or |nullptr|. * * It's perfectly okay to return a UniquePtr from a method to assure the related * resource is properly deleted. You'll need to use |Move()| when returning a * local UniquePtr. Otherwise you can return |nullptr|, or you can return * |UniquePtr(ptr)|. * * 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 class UniquePtr { public: typedef T* Pointer; typedef T ElementType; typedef D DeleterType; private: Pair 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|. */ MOZ_CONSTEXPR UniquePtr() : mTuple(static_cast(nullptr), DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } /** * Construct a UniquePtr containing |aPtr|. */ explicit UniquePtr(Pointer aPtr) : mTuple(aPtr, DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } UniquePtr(Pointer aPtr, typename Conditional::value, D, const D&>::Type aD1) : mTuple(aPtr, aD1) {} // If you encounter an error with MSVC10 about RemoveReference below, along // the lines that "more than one partial specialization matches the template // argument list": don't use UniquePtr! Ideally // you should make deletion use the same function every time, using a // deleter policy: // // // BAD, won't compile with MSVC10, deleter doesn't need to be a // // variable at all // typedef void (&FreeSignature)(void*); // UniquePtr ptr((int*) malloc(sizeof(int)), free); // // // GOOD, compiles with MSVC10, deletion behavior statically known and // // optimizable // struct DeleteByFreeing // { // void operator()(void* aPtr) { free(aPtr); } // }; // // If deletion really, truly, must be a variable: you might be able to work // around this with a deleter class that contains the function reference. // But this workaround is untried and untested, because variable deletion // behavior really isn't something you should use. UniquePtr(Pointer aPtr, typename RemoveReference::Type&& aD2) : mTuple(aPtr, Move(aD2)) { static_assert(!IsReference::value, "rvalue deleter can't be stored by reference"); } UniquePtr(UniquePtr&& aOther) : mTuple(aOther.release(), Forward(aOther.getDeleter())) {} template UniquePtr(N, typename EnableIf::value, int>::Type aDummy = 0) : mTuple(static_cast(nullptr), DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } template UniquePtr(UniquePtr&& aOther, typename EnableIf::Pointer, Pointer>::value && !IsArray::value && (IsReference::value ? IsSame::value : IsConvertible::value), int>::Type aDummy = 0) : mTuple(aOther.release(), Forward(aOther.getDeleter())) { } ~UniquePtr() { reset(nullptr); } UniquePtr& operator=(UniquePtr&& aOther) { reset(aOther.release()); getDeleter() = Forward(aOther.getDeleter()); return *this; } template UniquePtr& operator=(UniquePtr&& aOther) { static_assert(IsConvertible::Pointer, Pointer>::value, "incompatible UniquePtr pointees"); static_assert(!IsArray::value, "can't assign from UniquePtr holding an array"); reset(aOther.release()); getDeleter() = Forward(aOther.getDeleter()); return *this; } UniquePtr& operator=(NullptrT aNull) { MOZ_ASSERT(aNull == nullptr); reset(nullptr); return *this; } T& operator*() const { return *get(); } Pointer operator->() const { MOZ_ASSERT(get(), "dereferencing a UniquePtr containing nullptr"); return get(); } Pointer get() const { return ptr(); } DeleterType& getDeleter() { return del(); } const DeleterType& getDeleter() const { return del(); } private: typedef void (UniquePtr::* ConvertibleToBool)(double, char); void nonNull(double, char) {} public: operator ConvertibleToBool() const { return get() != nullptr ? &UniquePtr::nonNull : nullptr; } Pointer release() { Pointer p = ptr(); ptr() = nullptr; return p; } void reset(Pointer aPtr = Pointer()) { Pointer old = ptr(); ptr() = aPtr; if (old != nullptr) { getDeleter()(old); } } void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); } private: UniquePtr(const UniquePtr& aOther) MOZ_DELETE; // construct using Move()! void operator=(const UniquePtr& aOther) MOZ_DELETE; // assign using Move()! }; // In case you didn't read the comment by the main definition (you should!): the // UniquePtr 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 class UniquePtr { public: typedef T* Pointer; typedef T ElementType; typedef D DeleterType; private: Pair mTuple; public: /** * Construct a UniquePtr containing nullptr. */ MOZ_CONSTEXPR UniquePtr() : mTuple(static_cast(nullptr), DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } /** * Construct a UniquePtr containing |aPtr|. */ explicit UniquePtr(Pointer aPtr) : mTuple(aPtr, DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } private: // 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 UniquePtr(U&& aU, typename EnableIf::value && IsConvertible::value, int>::Type aDummy = 0) MOZ_DELETE; public: UniquePtr(Pointer aPtr, typename Conditional::value, D, const D&>::Type aD1) : mTuple(aPtr, aD1) {} // If you encounter an error with MSVC10 about RemoveReference below, along // the lines that "more than one partial specialization matches the template // argument list": don't use UniquePtr! See the // comment by this constructor in the non-T[] specialization above. UniquePtr(Pointer aPtr, typename RemoveReference::Type&& aD2) : mTuple(aPtr, Move(aD2)) { static_assert(!IsReference::value, "rvalue deleter can't be stored by reference"); } private: // Forbidden for the same reasons as stated above. template UniquePtr(U&& aU, V&& aV, typename EnableIf::value && IsConvertible::value, int>::Type aDummy = 0) MOZ_DELETE; public: UniquePtr(UniquePtr&& aOther) : mTuple(aOther.release(), Forward(aOther.getDeleter())) {} template UniquePtr(N, typename EnableIf::value, int>::Type aDummy = 0) : mTuple(static_cast(nullptr), DeleterType()) { static_assert(!IsPointer::value, "must provide a deleter instance"); static_assert(!IsReference::value, "must provide a deleter instance"); } ~UniquePtr() { reset(nullptr); } UniquePtr& operator=(UniquePtr&& aOther) { reset(aOther.release()); getDeleter() = Forward(aOther.getDeleter()); return *this; } UniquePtr& operator=(NullptrT) { reset(); return *this; } T& operator[](decltype(sizeof(int)) aIndex) const { return get()[aIndex]; } Pointer get() const { return mTuple.first(); } DeleterType& getDeleter() { return mTuple.second(); } const DeleterType& getDeleter() const { return mTuple.second(); } private: typedef void (UniquePtr::* ConvertibleToBool)(double, char); void nonNull(double, char) {} public: operator ConvertibleToBool() const { return get() != nullptr ? &UniquePtr::nonNull : nullptr; } 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); } } private: // Kill off all remaining overloads that aren't true nullptr (the overload // above should handle that) or emulated nullptr (which acts like int/long // on gcc 4.4/4.5). template void reset(U, typename EnableIf::value && !IsSame::Type>::value, int>::Type aDummy = 0) MOZ_DELETE; public: void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); } private: UniquePtr(const UniquePtr& aOther) MOZ_DELETE; // construct using Move()! void operator=(const UniquePtr& aOther) MOZ_DELETE; // assign using Move()! }; /** A default deletion policy using plain old operator delete. */ template class DefaultDelete { public: MOZ_CONSTEXPR DefaultDelete() {} template DefaultDelete(const DefaultDelete& aOther, typename EnableIf::value, int>::Type 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 class DefaultDelete { public: MOZ_CONSTEXPR DefaultDelete() {} void operator()(T* aPtr) const { static_assert(sizeof(T) > 0, "T must be complete"); delete[] aPtr; } private: template void operator()(U* aPtr) const MOZ_DELETE; }; template void Swap(UniquePtr& aX, UniquePtr& aY) { aX.swap(aY); } template bool operator==(const UniquePtr& aX, const UniquePtr& aY) { return aX.get() == aY.get(); } template bool operator!=(const UniquePtr& aX, const UniquePtr& aY) { return aX.get() != aY.get(); } template bool operator==(const UniquePtr& aX, NullptrT aNull) { MOZ_ASSERT(aNull == nullptr); return !aX; } template bool operator==(NullptrT aNull, const UniquePtr& aX) { MOZ_ASSERT(aNull == nullptr); return !aX; } template bool operator!=(const UniquePtr& aX, NullptrT aNull) { MOZ_ASSERT(aNull == nullptr); return bool(aX); } template bool operator!=(NullptrT aNull, const UniquePtr& aX) { MOZ_ASSERT(aNull == nullptr); return bool(aX); } // No operator<, operator>, operator<=, operator>= for now because simplicity. namespace detail { template struct UniqueSelector { typedef UniquePtr SingleObject; }; template struct UniqueSelector { typedef UniquePtr UnknownBound; }; template struct UniqueSelector { typedef UniquePtr 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(...) are as follows. * * If Type is an array T[n]: * Disallowed, deleted, no overload for you! * If Type is an array T[]: * MakeUnique(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(...) are forwarded into a * |new T(...)| call, initializing the T as would happen if executing * |T(...)|. (Note: literal nullptr must not be provided as an argument to * MakeUnique, because nullptr may be emulated. See Move.h for details.) * * 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 renaming * the new'd type, whereas MakeUnique in concert with the |auto| keyword names * it only once: * * UniquePtr ptr1(new char()); // repetitive * auto ptr2 = MakeUnique(); // 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 p; * p = new char; // ERROR * p.reset(new char); // works, but fugly * p = MakeUnique(); // 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.) */ // We don't have variadic template support everywhere, so just hard-code arities // 0-5 for now. If you need more arguments, feel free to add the extra // overloads (and deletions for the T = E[N] case). // // Beware! Due to lack of true nullptr support in gcc 4.4 and 4.5, passing // literal nullptr to MakeUnique will not work on some platforms. See Move.h // for more details. template typename detail::UniqueSelector::SingleObject MakeUnique() { return UniquePtr(new T()); } template typename detail::UniqueSelector::SingleObject MakeUnique(A1&& aA1) { return UniquePtr(new T(Forward(aA1))); } template typename detail::UniqueSelector::SingleObject MakeUnique(A1&& aA1, A2&& aA2) { return UniquePtr(new T(Forward(aA1), Forward(aA2))); } template typename detail::UniqueSelector::SingleObject MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3) { return UniquePtr(new T(Forward(aA1), Forward(aA2), Forward(aA3))); } template typename detail::UniqueSelector::SingleObject MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4) { return UniquePtr(new T(Forward(aA1), Forward(aA2), Forward(aA3), Forward(aA4))); } template typename detail::UniqueSelector::SingleObject MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4, A5&& aA5) { return UniquePtr(new T(Forward(aA1), Forward(aA2), Forward(aA3), Forward(aA4), Forward(aA5))); } template typename detail::UniqueSelector::UnknownBound MakeUnique(decltype(sizeof(int)) aN) { typedef typename RemoveExtent::Type ArrayType; return UniquePtr(new ArrayType[aN]()); } template typename detail::UniqueSelector::KnownBound MakeUnique() MOZ_DELETE; template typename detail::UniqueSelector::KnownBound MakeUnique(A1&& aA1) MOZ_DELETE; template typename detail::UniqueSelector::KnownBound MakeUnique(A1&& aA1, A2&& aA2) MOZ_DELETE; template typename detail::UniqueSelector::KnownBound MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3) MOZ_DELETE; template typename detail::UniqueSelector::KnownBound MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4) MOZ_DELETE; template typename detail::UniqueSelector::KnownBound MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4, A5&& aA5) MOZ_DELETE; } // namespace mozilla #endif /* mozilla_UniquePtr_h */