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