mfbt/UniquePtr.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 /* Smart pointer managing sole ownership of a resource. */
   8
   9 #ifndef mozilla_UniquePtr_h
  10 #define mozilla_UniquePtr_h
  11
  12 #include "mozilla/Assertions.h"
  13 #include "mozilla/Attributes.h"
  14 #include "mozilla/Compiler.h"
  15 #include "mozilla/Move.h"
  16 #include "mozilla/NullPtr.h"
  17 #include "mozilla/Pair.h"
  18 #include "mozilla/TypeTraits.h"
  19
  20 namespace mozilla {
  21
  22 template<typename T> class DefaultDelete;
  23 template<typename T, class D = DefaultDelete<T>> class UniquePtr;
  24
  25 } // namespace mozilla
  26
  27 namespace mozilla {
  28
  29 /**
  30  * UniquePtr is a smart pointer that wholly owns a resource.  Ownership may be
  31  * transferred out of a UniquePtr through explicit action, but otherwise the
  32  * resource is destroyed when the UniquePtr is destroyed.
  33  *
  34  * UniquePtr is similar to C++98's std::auto_ptr, but it improves upon auto_ptr
  35  * in one crucial way: it's impossible to copy a UniquePtr.  Copying an auto_ptr
  36  * obviously *can't* copy ownership of its singly-owned resource.  So what
  37  * happens if you try to copy one?  Bizarrely, ownership is implicitly
  38  * *transferred*, preserving single ownership but breaking code that assumes a
  39  * copy of an object is identical to the original.  (This is why auto_ptr is
  40  * prohibited in STL containers.)
  41  *
  42  * UniquePtr solves this problem by being *movable* rather than copyable.
  43  * Instead of passing a |UniquePtr u| directly to the constructor or assignment
  44  * operator, you pass |Move(u)|.  In doing so you indicate that you're *moving*
  45  * ownership out of |u|, into the target of the construction/assignment.  After
  46  * the transfer completes, |u| contains |nullptr| and may be safely destroyed.
  47  * This preserves single ownership but also allows UniquePtr to be moved by
  48  * algorithms that have been made move-safe.  (Note: if |u| is instead a
  49  * temporary expression, don't use |Move()|: just pass the expression, because
  50  * it's already move-ready.  For more information see Move.h.)
  51  *
  52  * UniquePtr is also better than std::auto_ptr in that the deletion operation is
  53  * customizable.  An optional second template parameter specifies a class that
  54  * (through its operator()(T*)) implements the desired deletion policy.  If no
  55  * policy is specified, mozilla::DefaultDelete<T> is used -- which will either
  56  * |delete| or |delete[]| the resource, depending whether the resource is an
  57  * array.  Custom deletion policies ideally should be empty classes (no member
  58  * fields, no member fields in base classes, no virtual methods/inheritance),
  59  * because then UniquePtr can be just as efficient as a raw pointer.
  60  *
  61  * Use of UniquePtr proceeds like so:
  62  *
  63  *   UniquePtr<int> g1; // initializes to nullptr
  64  *   g1.reset(new int); // switch resources using reset()
  65  *   g1 = nullptr; // clears g1, deletes the int
  66  *
  67  *   UniquePtr<int> g2(new int); // owns that int
  68  *   int* p = g2.release(); // g2 leaks its int -- still requires deletion
  69  *   delete p; // now freed
  70  *
  71  *   struct S { int x; S(int x) : x(x) {} };
  72  *   UniquePtr<S> g3, g4(new S(5));
  73  *   g3 = Move(g4); // g3 owns the S, g4 cleared
  74  *   S* p = g3.get(); // g3 still owns |p|
  75  *   assert(g3->x == 5); // operator-> works (if .get() != nullptr)
  76  *   assert((*g3).x == 5); // also operator* (again, if not cleared)
  77  *   Swap(g3, g4); // g4 now owns the S, g3 cleared
  78  *   g3.swap(g4);  // g3 now owns the S, g4 cleared
  79  *   UniquePtr<S> g5(Move(g3)); // g5 owns the S, g3 cleared
  80  *   g5.reset(); // deletes the S, g5 cleared
  81  *
  82  *   struct FreePolicy { void operator()(void* p) { free(p); } };
  83  *   UniquePtr<int, FreePolicy> g6(static_cast<int*>(malloc(sizeof(int))));
  84  *   int* ptr = g6.get();
  85  *   g6 = nullptr; // calls free(ptr)
  86  *
  87  * Now, carefully note a few things you *can't* do:
  88  *
  89  *   UniquePtr<int> b1;
  90  *   b1 = new int; // BAD: can only assign another UniquePtr
  91  *   int* ptr = b1; // BAD: no auto-conversion to pointer, use get()
  92  *
  93  *   UniquePtr<int> b2(b1); // BAD: can't copy a UniquePtr
  94  *   UniquePtr<int> b3 = b1; // BAD: can't copy-assign a UniquePtr
  95  *
  96  * (Note that changing a UniquePtr to store a direct |new| expression is
  97  * permitted, but usually you should use MakeUnique, defined at the end of this
  98  * header.)
  99  *
 100  * A few miscellaneous notes:
 101  *
 102  * UniquePtr, when not instantiated for an array type, can be move-constructed
 103  * and move-assigned, not only from itself but from "derived" UniquePtr<U, E>
 104  * instantiations where U converts to T and E converts to D.  If you want to use
 105  * this, you're going to have to specify a deletion policy for both UniquePtr
 106  * instantations, and T pretty much has to have a virtual destructor.  In other
 107  * words, this doesn't work:
 108  *
 109  *   struct Base { virtual ~Base() {} };
 110  *   struct Derived : Base {};
 111  *
 112  *   UniquePtr<Base> b1;
 113  *   // BAD: DefaultDelete<Base> and DefaultDelete<Derived> don't interconvert
 114  *   UniquePtr<Derived> d1(Move(b));
 115  *
 116  *   UniquePtr<Base> b2;
 117  *   UniquePtr<Derived, DefaultDelete<Base>> d2(Move(b2)); // okay
 118  *
 119  * UniquePtr is specialized for array types.  Specializing with an array type
 120  * creates a smart-pointer version of that array -- not a pointer to such an
 121  * array.
 122  *
 123  *   UniquePtr<int[]> arr(new int[5]);
 124  *   arr[0] = 4;
 125  *
 126  * What else is different?  Deletion of course uses |delete[]|.  An operator[]
 127  * is provided.  Functionality that doesn't make sense for arrays is removed.
 128  * The constructors and mutating methods only accept array pointers (not T*, U*
 129  * that converts to T*, or UniquePtr<U[]> or UniquePtr<U>) or |nullptr|.
 130  *
 131  * It's perfectly okay to return a UniquePtr from a method to assure the related
 132  * resource is properly deleted.  You'll need to use |Move()| when returning a
 133  * local UniquePtr.  Otherwise you can return |nullptr|, or you can return
 134  * |UniquePtr(ptr)|.
 135  *
 136  * UniquePtr will commonly be a member of a class, with lifetime equivalent to
 137  * that of that class.  If you want to expose the related resource, you could
 138  * expose a raw pointer via |get()|, but ownership of a raw pointer is
 139  * inherently unclear.  So it's better to expose a |const UniquePtr&| instead.
 140  * This prohibits mutation but still allows use of |get()| when needed (but
 141  * operator-> is preferred).  Of course, you can only use this smart pointer as
 142  * long as the enclosing class instance remains live -- no different than if you
 143  * exposed the |get()| raw pointer.
 144  *
 145  * To pass a UniquePtr-managed resource as a pointer, use a |const UniquePtr&|
 146  * argument.  To specify an inout parameter (where the method may or may not
 147  * take ownership of the resource, or reset it), or to specify an out parameter
 148  * (where simply returning a |UniquePtr| isn't possible), use a |UniquePtr&|
 149  * argument.  To unconditionally transfer ownership of a UniquePtr
 150  * into a method, use a |UniquePtr| argument.  To conditionally transfer
 151  * ownership of a resource into a method, should the method want it, use a
 152  * |UniquePtr&&| argument.
 153  */
 154 template<typename T, class D>
 155 class UniquePtr
 156 {
 157 public:
 158   typedef T* Pointer;
 159   typedef T ElementType;
 160   typedef D DeleterType;
 161
 162 private:
 163   Pair<Pointer, DeleterType> mTuple;
 164
 165   Pointer& ptr() { return mTuple.first(); }
 166   const Pointer& ptr() const { return mTuple.first(); }
 167
 168   DeleterType& del() { return mTuple.second(); }
 169   const DeleterType& del() const { return mTuple.second(); }
 170
 171 public:
 172   /**
 173    * Construct a UniquePtr containing |nullptr|.
 174    */
 175   MOZ_CONSTEXPR UniquePtr()
 176     : mTuple(static_cast<Pointer>(nullptr), DeleterType())
 177   {
 178     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 179     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 180   }
 181
 182   /**
 183    * Construct a UniquePtr containing |aPtr|.
 184    */
 185   explicit UniquePtr(Pointer aPtr)
 186     : mTuple(aPtr, DeleterType())
 187   {
 188     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 189     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 190   }
 191
 192   UniquePtr(Pointer aPtr,
 193             typename Conditional<IsReference<D>::value,
 194                                  D,
 195                                  const D&>::Type aD1)
 196     : mTuple(aPtr, aD1)
 197   {}
 198
 199   // If you encounter an error with MSVC10 about RemoveReference below, along
 200   // the lines that "more than one partial specialization matches the template
 201   // argument list": don't use UniquePtr<T, reference to function>!  Ideally
 202   // you should make deletion use the same function every time, using a
 203   // deleter policy:
 204   //
 205   //   // BAD, won't compile with MSVC10, deleter doesn't need to be a
 206   //   // variable at all
 207   //   typedef void (&FreeSignature)(void*);
 208   //   UniquePtr<int, FreeSignature> ptr((int*) malloc(sizeof(int)), free);
 209   //
 210   //   // GOOD, compiles with MSVC10, deletion behavior statically known and
 211   //   // optimizable
 212   //   struct DeleteByFreeing
 213   //   {
 214   //     void operator()(void* aPtr) { free(aPtr); }
 215   //   };
 216   //
 217   // If deletion really, truly, must be a variable: you might be able to work
 218   // around this with a deleter class that contains the function reference.
 219   // But this workaround is untried and untested, because variable deletion
 220   // behavior really isn't something you should use.
 221   UniquePtr(Pointer aPtr,
 222             typename RemoveReference<D>::Type&& aD2)
 223     : mTuple(aPtr, Move(aD2))
 224   {
 225     static_assert(!IsReference<D>::value,
 226                   "rvalue deleter can't be stored by reference");
 227   }
 228
 229   UniquePtr(UniquePtr&& aOther)
 230     : mTuple(aOther.release(), Forward<DeleterType>(aOther.getDeleter()))
 231   {}
 232
 233   template<typename N>
 234   UniquePtr(N,
 235             typename EnableIf<IsNullPointer<N>::value, int>::Type aDummy = 0)
 236     : mTuple(static_cast<Pointer>(nullptr), DeleterType())
 237   {
 238     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 239     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 240   }
 241
 242   template<typename U, class E>
 243   UniquePtr(UniquePtr<U, E>&& aOther,
 244             typename EnableIf<IsConvertible<typename UniquePtr<U, E>::Pointer,
 245                                             Pointer>::value &&
 246                               !IsArray<U>::value &&
 247                               (IsReference<D>::value
 248                                ? IsSame<D, E>::value
 249                                : IsConvertible<E, D>::value),
 250                               int>::Type aDummy = 0)
 251     : mTuple(aOther.release(), Forward<E>(aOther.getDeleter()))
 252   {
 253   }
 254
 255   ~UniquePtr() { reset(nullptr); }
 256
 257   UniquePtr& operator=(UniquePtr&& aOther)
 258   {
 259     reset(aOther.release());
 260     getDeleter() = Forward<DeleterType>(aOther.getDeleter());
 261     return *this;
 262   }
 263
 264   template<typename U, typename E>
 265   UniquePtr& operator=(UniquePtr<U, E>&& aOther)
 266   {
 267     static_assert(IsConvertible<typename UniquePtr<U, E>::Pointer,
 268                                 Pointer>::value,
 269                   "incompatible UniquePtr pointees");
 270     static_assert(!IsArray<U>::value,
 271                   "can't assign from UniquePtr holding an array");
 272
 273     reset(aOther.release());
 274     getDeleter() = Forward<E>(aOther.getDeleter());
 275     return *this;
 276   }
 277
 278   UniquePtr& operator=(NullptrT aNull)
 279   {
 280     MOZ_ASSERT(aNull == nullptr);
 281     reset(nullptr);
 282     return *this;
 283   }
 284
 285   T& operator*() const { return *get(); }
 286   Pointer operator->() const
 287   {
 288     MOZ_ASSERT(get(), "dereferencing a UniquePtr containing nullptr");
 289     return get();
 290   }
 291
 292   Pointer get() const { return ptr(); }
 293
 294   DeleterType& getDeleter() { return del(); }
 295   const DeleterType& getDeleter() const { return del(); }
 296
 297 private:
 298   typedef void (UniquePtr::* ConvertibleToBool)(double, char);
 299   void nonNull(double, char) {}
 300
 301 public:
 302   operator ConvertibleToBool() const
 303   {
 304     return get() != nullptr ? &UniquePtr::nonNull : nullptr;
 305   }
 306
 307   Pointer release()
 308   {
 309     Pointer p = ptr();
 310     ptr() = nullptr;
 311     return p;
 312   }
 313
 314   void reset(Pointer aPtr = Pointer())
 315   {
 316     Pointer old = ptr();
 317     ptr() = aPtr;
 318     if (old != nullptr) {
 319       getDeleter()(old);
 320     }
 321   }
 322
 323   void swap(UniquePtr& aOther)
 324   {
 325     mTuple.swap(aOther.mTuple);
 326   }
 327
 328 private:
 329   UniquePtr(const UniquePtr& aOther) MOZ_DELETE; // construct using Move()!
 330   void operator=(const UniquePtr& aOther) MOZ_DELETE; // assign using Move()!
 331 };
 332
 333 // In case you didn't read the comment by the main definition (you should!): the
 334 // UniquePtr<T[]> specialization exists to manage array pointers.  It deletes
 335 // such pointers using delete[], it will reject construction and modification
 336 // attempts using U* or U[].  Otherwise it works like the normal UniquePtr.
 337 template<typename T, class D>
 338 class UniquePtr<T[], D>
 339 {
 340 public:
 341   typedef T* Pointer;
 342   typedef T ElementType;
 343   typedef D DeleterType;
 344
 345 private:
 346   Pair<Pointer, DeleterType> mTuple;
 347
 348 public:
 349   /**
 350    * Construct a UniquePtr containing nullptr.
 351    */
 352   MOZ_CONSTEXPR UniquePtr()
 353     : mTuple(static_cast<Pointer>(nullptr), DeleterType())
 354   {
 355     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 356     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 357   }
 358
 359   /**
 360    * Construct a UniquePtr containing |aPtr|.
 361    */
 362   explicit UniquePtr(Pointer aPtr)
 363     : mTuple(aPtr, DeleterType())
 364   {
 365     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 366     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 367   }
 368
 369 private:
 370   // delete[] knows how to handle *only* an array of a single class type.  For
 371   // delete[] to work correctly, it must know the size of each element, the
 372   // fields and base classes of each element requiring destruction, and so on.
 373   // So forbid all overloads which would end up invoking delete[] on a pointer
 374   // of the wrong type.
 375   template<typename U>
 376   UniquePtr(U&& aU,
 377             typename EnableIf<IsPointer<U>::value &&
 378                               IsConvertible<U, Pointer>::value,
 379                               int>::Type aDummy = 0)
 380   MOZ_DELETE;
 381
 382 public:
 383   UniquePtr(Pointer aPtr,
 384             typename Conditional<IsReference<D>::value,
 385                                  D,
 386                                  const D&>::Type aD1)
 387     : mTuple(aPtr, aD1)
 388   {}
 389
 390   // If you encounter an error with MSVC10 about RemoveReference below, along
 391   // the lines that "more than one partial specialization matches the template
 392   // argument list": don't use UniquePtr<T[], reference to function>!  See the
 393   // comment by this constructor in the non-T[] specialization above.
 394   UniquePtr(Pointer aPtr,
 395             typename RemoveReference<D>::Type&& aD2)
 396     : mTuple(aPtr, Move(aD2))
 397   {
 398     static_assert(!IsReference<D>::value,
 399                   "rvalue deleter can't be stored by reference");
 400   }
 401
 402 private:
 403   // Forbidden for the same reasons as stated above.
 404   template<typename U, typename V>
 405   UniquePtr(U&& aU, V&& aV,
 406             typename EnableIf<IsPointer<U>::value &&
 407                               IsConvertible<U, Pointer>::value,
 408                               int>::Type aDummy = 0)
 409   MOZ_DELETE;
 410
 411 public:
 412   UniquePtr(UniquePtr&& aOther)
 413     : mTuple(aOther.release(), Forward<DeleterType>(aOther.getDeleter()))
 414   {}
 415
 416   template<typename N>
 417   UniquePtr(N,
 418             typename EnableIf<IsNullPointer<N>::value, int>::Type aDummy = 0)
 419     : mTuple(static_cast<Pointer>(nullptr), DeleterType())
 420   {
 421     static_assert(!IsPointer<D>::value, "must provide a deleter instance");
 422     static_assert(!IsReference<D>::value, "must provide a deleter instance");
 423   }
 424
 425   ~UniquePtr() { reset(nullptr); }
 426
 427   UniquePtr& operator=(UniquePtr&& aOther)
 428   {
 429     reset(aOther.release());
 430     getDeleter() = Forward<DeleterType>(aOther.getDeleter());
 431     return *this;
 432   }
 433
 434   UniquePtr& operator=(NullptrT)
 435   {
 436     reset();
 437     return *this;
 438   }
 439
 440   T& operator[](decltype(sizeof(int)) aIndex) const { return get()[aIndex]; }
 441   Pointer get() const { return mTuple.first(); }
 442
 443   DeleterType& getDeleter() { return mTuple.second(); }
 444   const DeleterType& getDeleter() const { return mTuple.second(); }
 445
 446 private:
 447   typedef void (UniquePtr::* ConvertibleToBool)(double, char);
 448   void nonNull(double, char) {}
 449
 450 public:
 451   operator ConvertibleToBool() const
 452   {
 453     return get() != nullptr ? &UniquePtr::nonNull : nullptr;
 454   }
 455
 456   Pointer release()
 457   {
 458     Pointer p = mTuple.first();
 459     mTuple.first() = nullptr;
 460     return p;
 461   }
 462
 463   void reset(Pointer aPtr = Pointer())
 464   {
 465     Pointer old = mTuple.first();
 466     mTuple.first() = aPtr;
 467     if (old != nullptr) {
 468       mTuple.second()(old);
 469     }
 470   }
 471
 472 private:
 473   // Kill off all remaining overloads that aren't true nullptr (the overload
 474   // above should handle that) or emulated nullptr (which acts like int/long
 475   // on gcc 4.4/4.5).
 476   template<typename U>
 477   void reset(U,
 478              typename EnableIf<!IsNullPointer<U>::value &&
 479                                !IsSame<U,
 480                                        Conditional<(sizeof(int) == sizeof(void*)),
 481                                                    int,
 482                                                    long>::Type>::value,
 483                                int>::Type aDummy = 0)
 484   MOZ_DELETE;
 485
 486 public:
 487   void swap(UniquePtr& aOther) { mTuple.swap(aOther.mTuple); }
 488
 489 private:
 490   UniquePtr(const UniquePtr& aOther) MOZ_DELETE; // construct using Move()!
 491   void operator=(const UniquePtr& aOther) MOZ_DELETE; // assign using Move()!
 492 };
 493
 494 /** A default deletion policy using plain old operator delete. */
 495 template<typename T>
 496 class DefaultDelete
 497 {
 498 public:
 499   MOZ_CONSTEXPR DefaultDelete() {}
 500
 501   template<typename U>
 502   DefaultDelete(const DefaultDelete<U>& aOther,
 503                 typename EnableIf<mozilla::IsConvertible<U*, T*>::value,
 504                                   int>::Type aDummy = 0)
 505   {}
 506
 507   void operator()(T* aPtr) const
 508   {
 509     static_assert(sizeof(T) > 0, "T must be complete");
 510     delete aPtr;
 511   }
 512 };
 513
 514 /** A default deletion policy using operator delete[]. */
 515 template<typename T>
 516 class DefaultDelete<T[]>
 517 {
 518 public:
 519   MOZ_CONSTEXPR DefaultDelete() {}
 520
 521   void operator()(T* aPtr) const
 522   {
 523     static_assert(sizeof(T) > 0, "T must be complete");
 524     delete[] aPtr;
 525   }
 526
 527 private:
 528   template<typename U>
 529   void operator()(U* aPtr) const MOZ_DELETE;
 530 };
 531
 532 template<typename T, class D>
 533 void
 534 Swap(UniquePtr<T, D>& aX, UniquePtr<T, D>& aY)
 535 {
 536   aX.swap(aY);
 537 }
 538
 539 template<typename T, class D, typename U, class E>
 540 bool
 541 operator==(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY)
 542 {
 543   return aX.get() == aY.get();
 544 }
 545
 546 template<typename T, class D, typename U, class E>
 547 bool
 548 operator!=(const UniquePtr<T, D>& aX, const UniquePtr<U, E>& aY)
 549 {
 550   return aX.get() != aY.get();
 551 }
 552
 553 template<typename T, class D>
 554 bool
 555 operator==(const UniquePtr<T, D>& aX, NullptrT aNull)
 556 {
 557   MOZ_ASSERT(aNull == nullptr);
 558   return !aX;
 559 }
 560
 561 template<typename T, class D>
 562 bool
 563 operator==(NullptrT aNull, const UniquePtr<T, D>& aX)
 564 {
 565   MOZ_ASSERT(aNull == nullptr);
 566   return !aX;
 567 }
 568
 569 template<typename T, class D>
 570 bool
 571 operator!=(const UniquePtr<T, D>& aX, NullptrT aNull)
 572 {
 573   MOZ_ASSERT(aNull == nullptr);
 574   return bool(aX);
 575 }
 576
 577 template<typename T, class D>
 578 bool
 579 operator!=(NullptrT aNull, const UniquePtr<T, D>& aX)
 580 {
 581   MOZ_ASSERT(aNull == nullptr);
 582   return bool(aX);
 583 }
 584
 585 // No operator<, operator>, operator<=, operator>= for now because simplicity.
 586
 587 namespace detail {
 588
 589 template<typename T>
 590 struct UniqueSelector
 591 {
 592   typedef UniquePtr<T> SingleObject;
 593 };
 594
 595 template<typename T>
 596 struct UniqueSelector<T[]>
 597 {
 598   typedef UniquePtr<T[]> UnknownBound;
 599 };
 600
 601 template<typename T, decltype(sizeof(int)) N>
 602 struct UniqueSelector<T[N]>
 603 {
 604   typedef UniquePtr<T[N]> KnownBound;
 605 };
 606
 607 } // namespace detail
 608
 609 /**
 610  * MakeUnique is a helper function for allocating new'd objects and arrays,
 611  * returning a UniquePtr containing the resulting pointer.  The semantics of
 612  * MakeUnique<Type>(...) are as follows.
 613  *
 614  *   If Type is an array T[n]:
 615  *     Disallowed, deleted, no overload for you!
 616  *   If Type is an array T[]:
 617  *     MakeUnique<T[]>(size_t) is the only valid overload.  The pointer returned
 618  *     is as if by |new T[n]()|, which value-initializes each element.  (If T
 619  *     isn't a class type, this will zero each element.  If T is a class type,
 620  *     then roughly speaking, each element will be constructed using its default
 621  *     constructor.  See C++11 [dcl.init]p7 for the full gory details.)
 622  *   If Type is non-array T:
 623  *     The arguments passed to MakeUnique<T>(...) are forwarded into a
 624  *     |new T(...)| call, initializing the T as would happen if executing
 625  *     |T(...)|.  (Note: literal nullptr must not be provided as an argument to
 626  *     MakeUnique, because nullptr may be emulated.  See Move.h for details.)
 627  *
 628  * There are various benefits to using MakeUnique instead of |new| expressions.
 629  *
 630  * First, MakeUnique eliminates use of |new| from code entirely.  If objects are
 631  * only created through UniquePtr, then (assuming all explicit release() calls
 632  * are safe, including transitively, and no type-safety casting funniness)
 633  * correctly maintained ownership of the UniquePtr guarantees no leaks are
 634  * possible.  (This pays off best if a class is only ever created through a
 635  * factory method on the class, using a private constructor.)
 636  *
 637  * Second, initializing a UniquePtr using a |new| expression requires renaming
 638  * the new'd type, whereas MakeUnique in concert with the |auto| keyword names
 639  * it only once:
 640  *
 641  *   UniquePtr<char> ptr1(new char()); // repetitive
 642  *   auto ptr2 = MakeUnique<char>();   // shorter
 643  *
 644  * Of course this assumes the reader understands the operation MakeUnique
 645  * performs.  In the long run this is probably a reasonable assumption.  In the
 646  * short run you'll have to use your judgment about what readers can be expected
 647  * to know, or to quickly look up.
 648  *
 649  * Third, a call to MakeUnique can be assigned directly to a UniquePtr.  In
 650  * contrast you can't assign a pointer into a UniquePtr without using the
 651  * cumbersome reset().
 652  *
 653  *   UniquePtr<char> p;
 654  *   p = new char;           // ERROR
 655  *   p.reset(new char);      // works, but fugly
 656  *   p = MakeUnique<char>(); // preferred
 657  *
 658  * (And third, although not relevant to Mozilla: MakeUnique is exception-safe.
 659  * An exception thrown after |new T| succeeds will leak that memory, unless the
 660  * pointer is assigned to an object that will manage its ownership.  UniquePtr
 661  * ably serves this function.)
 662  */
 663
 664 // We don't have variadic template support everywhere, so just hard-code arities
 665 // 0-8 for now.  If you need more arguments, feel free to add the extra
 666 // overloads (and deletions for the T = E[N] case).
 667 //
 668 // Beware!  Due to lack of true nullptr support in gcc 4.4 and 4.5, passing
 669 // literal nullptr to MakeUnique will not work on some platforms.  See Move.h
 670 // for more details.
 671
 672 template<typename T>
 673 typename detail::UniqueSelector<T>::SingleObject
 674 MakeUnique()
 675 {
 676   return UniquePtr<T>(new T());
 677 }
 678
 679 template<typename T, typename A1>
 680 typename detail::UniqueSelector<T>::SingleObject
 681 MakeUnique(A1&& aA1)
 682 {
 683   return UniquePtr<T>(new T(Forward<A1>(aA1)));
 684 }
 685
 686 template<typename T, typename A1, typename A2>
 687 typename detail::UniqueSelector<T>::SingleObject
 688 MakeUnique(A1&& aA1, A2&& aA2)
 689 {
 690   return UniquePtr<T>(new T(Forward<A1>(aA1), Forward<A2>(aA2)));
 691 }
 692
 693 template<typename T, typename A1, typename A2, typename A3>
 694 typename detail::UniqueSelector<T>::SingleObject
 695 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3)
 696 {
 697   return UniquePtr<T>(new T(Forward<A1>(aA1), Forward<A2>(aA2),
 698                             Forward<A3>(aA3)));
 699 }
 700
 701 template<typename T, typename A1, typename A2, typename A3, typename A4>
 702 typename detail::UniqueSelector<T>::SingleObject
 703 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4)
 704 {
 705   return UniquePtr<T>(new T(Forward<A1>(aA1), Forward<A2>(aA2),
 706                             Forward<A3>(aA3), Forward<A4>(aA4)));
 707 }
 708
 709 template<typename T, typename A1, typename A2, typename A3, typename A4,
 710          typename A5>
 711 typename detail::UniqueSelector<T>::SingleObject
 712 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4, A5&& aA5)
 713 {
 714   return UniquePtr<T>(new T(Forward<A1>(aA1), Forward<A2>(aA2),
 715                             Forward<A3>(aA3), Forward<A4>(aA4),
 716                             Forward<A5>(aA5)));
 717 }
 718
 719 template<typename T, typename A1, typename A2, typename A3, typename A4,
 720          typename A5, typename A6>
 721 typename detail::UniqueSelector<T>::SingleObject
 722 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5, A6&& a6)
 723 {
 724   return UniquePtr<T>(new T(Forward<A1>(a1), Forward<A2>(a2),
 725                             Forward<A3>(a3), Forward<A4>(a4),
 726                             Forward<A5>(a5), Forward<A6>(a6)));
 727 }
 728
 729 template<typename T, typename A1, typename A2, typename A3, typename A4,
 730          typename A5, typename A6, typename A7>
 731 typename detail::UniqueSelector<T>::SingleObject
 732 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5, A6&& a6, A7&& a7)
 733 {
 734   return UniquePtr<T>(new T(Forward<A1>(a1), Forward<A2>(a2),
 735                             Forward<A3>(a3), Forward<A4>(a4),
 736                             Forward<A5>(a5), Forward<A6>(a6),
 737                             Forward<A7>(a7)));
 738 }
 739
 740 template<typename T, typename A1, typename A2, typename A3, typename A4,
 741          typename A5, typename A6, typename A7, typename A8>
 742 typename detail::UniqueSelector<T>::SingleObject
 743 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5, A6&& a6, A7&& a7,
 744            A8&& a8)
 745 {
 746   return UniquePtr<T>(new T(Forward<A1>(a1), Forward<A2>(a2),
 747                             Forward<A3>(a3), Forward<A4>(a4),
 748                             Forward<A5>(a5), Forward<A6>(a6),
 749                             Forward<A7>(a7), Forward<A8>(a8)));
 750 }
 751
 752 template<typename T>
 753 typename detail::UniqueSelector<T>::UnknownBound
 754 MakeUnique(decltype(sizeof(int)) aN)
 755 {
 756   typedef typename RemoveExtent<T>::Type ArrayType;
 757   return UniquePtr<T>(new ArrayType[aN]());
 758 }
 759
 760 template<typename T>
 761 typename detail::UniqueSelector<T>::KnownBound
 762 MakeUnique() MOZ_DELETE;
 763
 764 template<typename T, typename A1>
 765 typename detail::UniqueSelector<T>::KnownBound
 766 MakeUnique(A1&& aA1) MOZ_DELETE;
 767
 768 template<typename T, typename A1, typename A2>
 769 typename detail::UniqueSelector<T>::KnownBound
 770 MakeUnique(A1&& aA1, A2&& aA2) MOZ_DELETE;
 771
 772 template<typename T, typename A1, typename A2, typename A3>
 773 typename detail::UniqueSelector<T>::KnownBound
 774 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3) MOZ_DELETE;
 775
 776 template<typename T, typename A1, typename A2, typename A3, typename A4>
 777 typename detail::UniqueSelector<T>::KnownBound
 778 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4) MOZ_DELETE;
 779
 780 template<typename T, typename A1, typename A2, typename A3, typename A4,
 781          typename A5>
 782 typename detail::UniqueSelector<T>::KnownBound
 783 MakeUnique(A1&& aA1, A2&& aA2, A3&& aA3, A4&& aA4, A5&& aA5) MOZ_DELETE;
 784
 785 template<typename T, typename A1, typename A2, typename A3, typename A4,
 786          typename A5, typename A6>
 787 typename detail::UniqueSelector<T>::KnownBound
 788 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5,
 789            A6&& a6) MOZ_DELETE;
 790
 791 template<typename T, typename A1, typename A2, typename A3, typename A4,
 792          typename A5, typename A6, typename A7>
 793 typename detail::UniqueSelector<T>::KnownBound
 794 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5, A6&& a6,
 795            A7&& a7) MOZ_DELETE;
 796
 797 template<typename T, typename A1, typename A2, typename A3, typename A4,
 798          typename A5, typename A6, typename A7, typename A8>
 799 typename detail::UniqueSelector<T>::KnownBound
 800 MakeUnique(A1&& a1, A2&& a2, A3&& a3, A4&& a4, A5&& a5, A6&& a6,
 801            A7&& a7, A8&& a8) MOZ_DELETE;
 802
 803 } // namespace mozilla
 804
 805 #endif /* mozilla_UniquePtr_h */