Version 5.2.6.1, tag libreoffice-5.2.6.1
[LibreOffice.git] / onlineupdate / source / update / inc / mozilla / UniquePtr.h
blob6fad8d1cfb8ae65b7b4f70968116a074edfb3df9
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/. */
7 /* Smart pointer managing sole ownership of a resource. */
9 #ifndef mozilla_UniquePtr_h
10 #define mozilla_UniquePtr_h
12 #include "mozilla/Assertions.h"
13 #include "mozilla/Attributes.h"
14 #include "mozilla/Compiler.h"
15 #include "mozilla/Move.h"
16 #include "mozilla/Pair.h"
17 #include "mozilla/TypeTraits.h"
19 namespace mozilla {
21 template<typename T> class DefaultDelete;
22 template<typename T, class D = DefaultDelete<T>> class UniquePtr;
24 } // namespace mozilla
26 namespace mozilla {
28 /**
29 * UniquePtr is a smart pointer that wholly owns a resource. Ownership may be
30 * transferred out of a UniquePtr through explicit action, but otherwise the
31 * resource is destroyed when the UniquePtr is destroyed.
33 * UniquePtr is similar to C++98's std::auto_ptr, but it improves upon auto_ptr
34 * in one crucial way: it's impossible to copy a UniquePtr. Copying an auto_ptr
35 * obviously *can't* copy ownership of its singly-owned resource. So what
36 * happens if you try to copy one? Bizarrely, ownership is implicitly
37 * *transferred*, preserving single ownership but breaking code that assumes a
38 * copy of an object is identical to the original. (This is why auto_ptr is
39 * prohibited in STL containers.)
41 * UniquePtr solves this problem by being *movable* rather than copyable.
42 * Instead of passing a |UniquePtr u| directly to the constructor or assignment
43 * operator, you pass |Move(u)|. In doing so you indicate that you're *moving*
44 * ownership out of |u|, into the target of the construction/assignment. After
45 * the transfer completes, |u| contains |nullptr| and may be safely destroyed.
46 * This preserves single ownership but also allows UniquePtr to be moved by
47 * algorithms that have been made move-safe. (Note: if |u| is instead a
48 * temporary expression, don't use |Move()|: just pass the expression, because
49 * it's already move-ready. For more information see Move.h.)
51 * UniquePtr is also better than std::auto_ptr in that the deletion operation is
52 * customizable. An optional second template parameter specifies a class that
53 * (through its operator()(T*)) implements the desired deletion policy. If no
54 * policy is specified, mozilla::DefaultDelete<T> is used -- which will either
55 * |delete| or |delete[]| the resource, depending whether the resource is an
56 * array. Custom deletion policies ideally should be empty classes (no member
57 * fields, no member fields in base classes, no virtual methods/inheritance),
58 * because then UniquePtr can be just as efficient as a raw pointer.
60 * Use of UniquePtr proceeds like so:
62 * UniquePtr<int> g1; // initializes to nullptr
63 * g1.reset(new int); // switch resources using reset()
64 * g1 = nullptr; // clears g1, deletes the int
66 * UniquePtr<int> g2(new int); // owns that int
67 * int* p = g2.release(); // g2 leaks its int -- still requires deletion
68 * delete p; // now freed
70 * struct S { int x; S(int x) : x(x) {} };
71 * UniquePtr<S> g3, g4(new S(5));
72 * g3 = Move(g4); // g3 owns the S, g4 cleared
73 * S* p = g3.get(); // g3 still owns |p|
74 * assert(g3->x == 5); // operator-> works (if .get() != nullptr)
75 * assert((*g3).x == 5); // also operator* (again, if not cleared)
76 * Swap(g3, g4); // g4 now owns the S, g3 cleared
77 * g3.swap(g4); // g3 now owns the S, g4 cleared
78 * UniquePtr<S> g5(Move(g3)); // g5 owns the S, g3 cleared
79 * g5.reset(); // deletes the S, g5 cleared
81 * struct FreePolicy { void operator()(void* p) { free(p); } };
82 * UniquePtr<int, FreePolicy> g6(static_cast<int*>(malloc(sizeof(int))));
83 * int* ptr = g6.get();
84 * g6 = nullptr; // calls free(ptr)
86 * Now, carefully note a few things you *can't* do:
88 * UniquePtr<int> b1;
89 * b1 = new int; // BAD: can only assign another UniquePtr
90 * int* ptr = b1; // BAD: no auto-conversion to pointer, use get()
92 * UniquePtr<int> b2(b1); // BAD: can't copy a UniquePtr
93 * UniquePtr<int> b3 = b1; // BAD: can't copy-assign a UniquePtr
95 * (Note that changing a UniquePtr to store a direct |new| expression is
96 * permitted, but usually you should use MakeUnique, defined at the end of this
97 * header.)
99 * A few miscellaneous notes:
101 * UniquePtr, when not instantiated for an array type, can be move-constructed
102 * and move-assigned, not only from itself but from "derived" UniquePtr<U, E>
103 * instantiations where U converts to T and E converts to D. If you want to use
104 * this, you're going to have to specify a deletion policy for both UniquePtr
105 * instantiations, and T pretty much has to have a virtual destructor. In other
106 * words, this doesn't work:
108 * struct Base { virtual ~Base() {} };
109 * struct Derived : Base {};
111 * UniquePtr<Base> b1;
112 * // BAD: DefaultDelete<Base> and DefaultDelete<Derived> don't interconvert
113 * UniquePtr<Derived> d1(Move(b));
115 * UniquePtr<Base> b2;
116 * UniquePtr<Derived, DefaultDelete<Base>> d2(Move(b2)); // okay
118 * UniquePtr is specialized for array types. Specializing with an array type
119 * creates a smart-pointer version of that array -- not a pointer to such an
120 * array.
122 * UniquePtr<int[]> arr(new int[5]);
123 * arr[0] = 4;
125 * What else is different? Deletion of course uses |delete[]|. An operator[]
126 * is provided. Functionality that doesn't make sense for arrays is removed.
127 * The constructors and mutating methods only accept array pointers (not T*, U*
128 * that converts to T*, or UniquePtr<U[]> or UniquePtr<U>) or |nullptr|.
130 * It's perfectly okay to return a UniquePtr from a method to assure the related
131 * resource is properly deleted. You'll need to use |Move()| when returning a
132 * local UniquePtr. Otherwise you can return |nullptr|, or you can return
133 * |UniquePtr(ptr)|.
135 * UniquePtr will commonly be a member of a class, with lifetime equivalent to
136 * that of that class. If you want to expose the related resource, you could
137 * expose a raw pointer via |get()|, but ownership of a raw pointer is
138 * inherently unclear. So it's better to expose a |const UniquePtr&| instead.
139 * This prohibits mutation but still allows use of |get()| when needed (but
140 * operator-> is preferred). Of course, you can only use this smart pointer as
141 * long as the enclosing class instance remains live -- no different than if you
142 * exposed the |get()| raw pointer.
144 * To pass a UniquePtr-managed resource as a pointer, use a |const UniquePtr&|
145 * argument. To specify an inout parameter (where the method may or may not
146 * take ownership of the resource, or reset it), or to specify an out parameter
147 * (where simply returning a |UniquePtr| isn't possible), use a |UniquePtr&|
148 * argument. To unconditionally transfer ownership of a UniquePtr
149 * into a method, use a |UniquePtr| argument. To conditionally transfer
150 * ownership of a resource into a method, should the method want it, use a
151 * |UniquePtr&&| argument.
153 template<typename T, class D>
154 class UniquePtr
156 public:
157 typedef T* Pointer;
158 typedef T ElementType;
159 typedef D DeleterType;
161 private:
162 Pair<Pointer, DeleterType> mTuple;
164 Pointer& ptr() { return mTuple.first(); }
165 const Pointer& ptr() const { return mTuple.first(); }
167 DeleterType& del() { return mTuple.second(); }
168 const DeleterType& del() const { return mTuple.second(); }
170 public:
172 * Construct a UniquePtr containing |nullptr|.
174 MOZ_CONSTEXPR UniquePtr()
175 : mTuple(static_cast<Pointer>(nullptr), DeleterType())
177 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
178 static_assert(!IsReference<D>::value, "must provide a deleter instance");
182 * Construct a UniquePtr containing |aPtr|.
184 explicit UniquePtr(Pointer aPtr)
185 : mTuple(aPtr, DeleterType())
187 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
188 static_assert(!IsReference<D>::value, "must provide a deleter instance");
191 UniquePtr(Pointer aPtr,
192 typename Conditional<IsReference<D>::value,
194 const D&>::Type aD1)
195 : mTuple(aPtr, aD1)
198 // If you encounter an error with MSVC10 about RemoveReference below, along
199 // the lines that "more than one partial specialization matches the template
200 // argument list": don't use UniquePtr<T, reference to function>! Ideally
201 // you should make deletion use the same function every time, using a
202 // deleter policy:
204 // // BAD, won't compile with MSVC10, deleter doesn't need to be a
205 // // variable at all
206 // typedef void (&FreeSignature)(void*);
207 // UniquePtr<int, FreeSignature> ptr((int*) malloc(sizeof(int)), free);
209 // // GOOD, compiles with MSVC10, deletion behavior statically known and
210 // // optimizable
211 // struct DeleteByFreeing
212 // {
213 // void operator()(void* aPtr) { free(aPtr); }
214 // };
216 // If deletion really, truly, must be a variable: you might be able to work
217 // around this with a deleter class that contains the function reference.
218 // But this workaround is untried and untested, because variable deletion
219 // behavior really isn't something you should use.
220 UniquePtr(Pointer aPtr,
221 typename RemoveReference<D>::Type&& aD2)
222 : mTuple(aPtr, Move(aD2))
224 static_assert(!IsReference<D>::value,
225 "rvalue deleter can't be stored by reference");
228 UniquePtr(UniquePtr&& aOther)
229 : mTuple(aOther.release(), Forward<DeleterType>(aOther.getDeleter()))
232 MOZ_IMPLICIT
233 UniquePtr(decltype(nullptr))
234 : mTuple(nullptr, DeleterType())
236 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
237 static_assert(!IsReference<D>::value, "must provide a deleter instance");
240 template<typename U, class E>
241 UniquePtr(UniquePtr<U, E>&& aOther,
242 typename EnableIf<IsConvertible<typename UniquePtr<U, E>::Pointer,
243 Pointer>::value &&
244 !IsArray<U>::value &&
245 (IsReference<D>::value
246 ? IsSame<D, E>::value
247 : IsConvertible<E, D>::value),
248 int>::Type aDummy = 0)
249 : mTuple(aOther.release(), Forward<E>(aOther.getDeleter()))
253 ~UniquePtr() { reset(nullptr); }
255 UniquePtr& operator=(UniquePtr&& aOther)
257 reset(aOther.release());
258 getDeleter() = Forward<DeleterType>(aOther.getDeleter());
259 return *this;
262 template<typename U, typename E>
263 UniquePtr& operator=(UniquePtr<U, E>&& aOther)
265 static_assert(IsConvertible<typename UniquePtr<U, E>::Pointer,
266 Pointer>::value,
267 "incompatible UniquePtr pointees");
268 static_assert(!IsArray<U>::value,
269 "can't assign from UniquePtr holding an array");
271 reset(aOther.release());
272 getDeleter() = Forward<E>(aOther.getDeleter());
273 return *this;
276 UniquePtr& operator=(decltype(nullptr))
278 reset(nullptr);
279 return *this;
282 T& operator*() const { return *get(); }
283 Pointer operator->() const
285 MOZ_ASSERT(get(), "dereferencing a UniquePtr containing nullptr");
286 return get();
289 explicit operator bool() const { return get() != nullptr; }
291 Pointer get() const { return ptr(); }
293 DeleterType& getDeleter() { return del(); }
294 const DeleterType& getDeleter() const { return del(); }
296 Pointer release()
298 Pointer p = ptr();
299 ptr() = nullptr;
300 return p;
303 void reset(Pointer aPtr = Pointer())
305 Pointer old = ptr();
306 ptr() = aPtr;
307 if (old != nullptr) {
308 getDeleter()(old);
312 void swap(UniquePtr& aOther)
314 mTuple.swap(aOther.mTuple);
317 private:
318 UniquePtr(const UniquePtr& aOther) = delete; // construct using Move()!
319 void operator=(const UniquePtr& aOther) = delete; // assign using Move()!
322 // In case you didn't read the comment by the main definition (you should!): the
323 // UniquePtr<T[]> specialization exists to manage array pointers. It deletes
324 // such pointers using delete[], it will reject construction and modification
325 // attempts using U* or U[]. Otherwise it works like the normal UniquePtr.
326 template<typename T, class D>
327 class UniquePtr<T[], D>
329 public:
330 typedef T* Pointer;
331 typedef T ElementType;
332 typedef D DeleterType;
334 private:
335 Pair<Pointer, DeleterType> mTuple;
337 public:
339 * Construct a UniquePtr containing nullptr.
341 MOZ_CONSTEXPR UniquePtr()
342 : mTuple(static_cast<Pointer>(nullptr), DeleterType())
344 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
345 static_assert(!IsReference<D>::value, "must provide a deleter instance");
349 * Construct a UniquePtr containing |aPtr|.
351 explicit UniquePtr(Pointer aPtr)
352 : mTuple(aPtr, DeleterType())
354 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
355 static_assert(!IsReference<D>::value, "must provide a deleter instance");
358 private:
359 // delete[] knows how to handle *only* an array of a single class type. For
360 // delete[] to work correctly, it must know the size of each element, the
361 // fields and base classes of each element requiring destruction, and so on.
362 // So forbid all overloads which would end up invoking delete[] on a pointer
363 // of the wrong type.
364 template<typename U>
365 UniquePtr(U&& aU,
366 typename EnableIf<IsPointer<U>::value &&
367 IsConvertible<U, Pointer>::value,
368 int>::Type aDummy = 0)
369 = delete;
371 public:
372 UniquePtr(Pointer aPtr,
373 typename Conditional<IsReference<D>::value,
375 const D&>::Type aD1)
376 : mTuple(aPtr, aD1)
379 // If you encounter an error with MSVC10 about RemoveReference below, along
380 // the lines that "more than one partial specialization matches the template
381 // argument list": don't use UniquePtr<T[], reference to function>! See the
382 // comment by this constructor in the non-T[] specialization above.
383 UniquePtr(Pointer aPtr,
384 typename RemoveReference<D>::Type&& aD2)
385 : mTuple(aPtr, Move(aD2))
387 static_assert(!IsReference<D>::value,
388 "rvalue deleter can't be stored by reference");
391 private:
392 // Forbidden for the same reasons as stated above.
393 template<typename U, typename V>
394 UniquePtr(U&& aU, V&& aV,
395 typename EnableIf<IsPointer<U>::value &&
396 IsConvertible<U, Pointer>::value,
397 int>::Type aDummy = 0)
398 = delete;
400 public:
401 UniquePtr(UniquePtr&& aOther)
402 : mTuple(aOther.release(), Forward<DeleterType>(aOther.getDeleter()))
405 MOZ_IMPLICIT
406 UniquePtr(decltype(nullptr))
407 : mTuple(nullptr, DeleterType())
409 static_assert(!IsPointer<D>::value, "must provide a deleter instance");
410 static_assert(!IsReference<D>::value, "must provide a deleter instance");
413 ~UniquePtr() { reset(nullptr); }
415 UniquePtr& operator=(UniquePtr&& aOther)
417 reset(aOther.release());
418 getDeleter() = Forward<DeleterType>(aOther.getDeleter());
419 return *this;
422 UniquePtr& operator=(decltype(nullptr))
424 reset();
425 return *this;
428 explicit operator bool() const { return get() != nullptr; }
430 T& operator[](decltype(sizeof(int)) aIndex) const { return get()[aIndex]; }
431 Pointer get() const { return mTuple.first(); }
433 DeleterType& getDeleter() { return mTuple.second(); }
434 const DeleterType& getDeleter() const { return mTuple.second(); }
436 Pointer release()
438 Pointer p = mTuple.first();
439 mTuple.first() = nullptr;
440 return p;
443 void reset(Pointer aPtr = Pointer())
445 Pointer old = mTuple.first();
446 mTuple.first() = aPtr;
447 if (old != nullptr) {
448 mTuple.second()(old);
452 void reset(decltype(nullptr))
454 Pointer old = mTuple.first();
455 mTuple.first() = nullptr;
456 if (old != nullptr) {
457 mTuple.second()(old);
461 private:
462 template<typename U>
463 void reset(U) = delete;
465 public:
466 void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); }
468 private:
469 UniquePtr(const UniquePtr& aOther) = delete; // construct using Move()!
470 void operator=(const UniquePtr& aOther) = delete; // assign using Move()!
473 /** A default deletion policy using plain old operator delete. */
474 template<typename T>
475 class DefaultDelete
477 public:
478 MOZ_CONSTEXPR DefaultDelete() {}
480 template<typename U>
481 DefaultDelete(const DefaultDelete<U>& aOther,
482 typename EnableIf<mozilla::IsConvertible<U*, T*>::value,
483 int>::Type aDummy = 0)
486 void operator()(T* aPtr) const
488 static_assert(sizeof(T) > 0, "T must be complete");
489 delete aPtr;
493 /** A default deletion policy using operator delete[]. */
494 template<typename T>
495 class DefaultDelete<T[]>
497 public:
498 MOZ_CONSTEXPR DefaultDelete() {}
500 void operator()(T* aPtr) const
502 static_assert(sizeof(T) > 0, "T must be complete");
503 delete[] aPtr;
506 private:
507 template<typename U>
508 void operator()(U* aPtr) const = delete;
511 template<typename T, class D>
512 void
513 Swap(UniquePtr<T, D>& aX, UniquePtr<T, D>& aY)
515 aX.swap(aY);
518 template<typename T, class D, typename U, class E>
519 bool
520 operator==(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY)
522 return aX.get() == aY.get();
525 template<typename T, class D, typename U, class E>
526 bool
527 operator!=(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY)
529 return aX.get() != aY.get();
532 template<typename T, class D>
533 bool
534 operator==(const UniquePtr<T, D>& aX, decltype(nullptr))
536 return !aX;
539 template<typename T, class D>
540 bool
541 operator==(decltype(nullptr), const UniquePtr<T, D>& aX)
543 return !aX;
546 template<typename T, class D>
547 bool
548 operator!=(const UniquePtr<T, D>& aX, decltype(nullptr))
550 return bool(aX);
553 template<typename T, class D>
554 bool
555 operator!=(decltype(nullptr), const UniquePtr<T, D>& aX)
557 return bool(aX);
560 // No operator<, operator>, operator<=, operator>= for now because simplicity.
562 namespace detail {
564 template<typename T>
565 struct UniqueSelector
567 typedef UniquePtr<T> SingleObject;
570 template<typename T>
571 struct UniqueSelector<T[]>
573 typedef UniquePtr<T[]> UnknownBound;
576 template<typename T, decltype(sizeof(int)) N>
577 struct UniqueSelector<T[N]>
579 typedef UniquePtr<T[N]> KnownBound;
582 } // namespace detail
585 * MakeUnique is a helper function for allocating new'd objects and arrays,
586 * returning a UniquePtr containing the resulting pointer. The semantics of
587 * MakeUnique<Type>(...) are as follows.
589 * If Type is an array T[n]:
590 * Disallowed, deleted, no overload for you!
591 * If Type is an array T[]:
592 * MakeUnique<T[]>(size_t) is the only valid overload. The pointer returned
593 * is as if by |new T[n]()|, which value-initializes each element. (If T
594 * isn't a class type, this will zero each element. If T is a class type,
595 * then roughly speaking, each element will be constructed using its default
596 * constructor. See C++11 [dcl.init]p7 for the full gory details.)
597 * If Type is non-array T:
598 * The arguments passed to MakeUnique<T>(...) are forwarded into a
599 * |new T(...)| call, initializing the T as would happen if executing
600 * |T(...)|.
602 * There are various benefits to using MakeUnique instead of |new| expressions.
604 * First, MakeUnique eliminates use of |new| from code entirely. If objects are
605 * only created through UniquePtr, then (assuming all explicit release() calls
606 * are safe, including transitively, and no type-safety casting funniness)
607 * correctly maintained ownership of the UniquePtr guarantees no leaks are
608 * possible. (This pays off best if a class is only ever created through a
609 * factory method on the class, using a private constructor.)
611 * Second, initializing a UniquePtr using a |new| expression requires repeating
612 * the name of the new'd type, whereas MakeUnique in concert with the |auto|
613 * keyword names it only once:
615 * UniquePtr<char> ptr1(new char()); // repetitive
616 * auto ptr2 = MakeUnique<char>(); // shorter
618 * Of course this assumes the reader understands the operation MakeUnique
619 * performs. In the long run this is probably a reasonable assumption. In the
620 * short run you'll have to use your judgment about what readers can be expected
621 * to know, or to quickly look up.
623 * Third, a call to MakeUnique can be assigned directly to a UniquePtr. In
624 * contrast you can't assign a pointer into a UniquePtr without using the
625 * cumbersome reset().
627 * UniquePtr<char> p;
628 * p = new char; // ERROR
629 * p.reset(new char); // works, but ugly
630 * p = MakeUnique<char>(); // preferred
632 * (And third, although not relevant to Mozilla: MakeUnique is exception-safe.
633 * An exception thrown after |new T| succeeds will leak that memory, unless the
634 * pointer is assigned to an object that will manage its ownership. UniquePtr
635 * ably serves this function.)
638 template<typename T, typename... Args>
639 typename detail::UniqueSelector<T>::SingleObject
640 MakeUnique(Args&&... aArgs)
642 return UniquePtr<T>(new T(Forward<Args>(aArgs)...));
645 template<typename T>
646 typename detail::UniqueSelector<T>::UnknownBound
647 MakeUnique(decltype(sizeof(int)) aN)
649 typedef typename RemoveExtent<T>::Type ArrayType;
650 return UniquePtr<T>(new ArrayType[aN]());
653 template<typename T, typename... Args>
654 typename detail::UniqueSelector<T>::KnownBound
655 MakeUnique(Args&&... aArgs) = delete;
657 } // namespace mozilla
659 #endif /* mozilla_UniquePtr_h */