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