mfbt/Move.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* C++11-style, but C++98-usable, "move references" implementation. */
   7
   8 #ifndef mozilla_Move_h_
   9 #define mozilla_Move_h_
  10
  11 namespace mozilla {
  12
  13 /*
  14  * "Move" References
  15  *
  16  * Some types can be copied much more efficiently if we know the original's
  17  * value need not be preserved --- that is, if we are doing a "move", not a
  18  * "copy". For example, if we have:
  19  *
  20  *   Vector<T> u;
  21  *   Vector<T> v(u);
  22  *
  23  * the constructor for v must apply a copy constructor to each element of u ---
  24  * taking time linear in the length of u. However, if we know we will not need u
  25  * any more once v has been initialized, then we could initialize v very
  26  * efficiently simply by stealing u's dynamically allocated buffer and giving it
  27  * to v --- a constant-time operation, regardless of the size of u.
  28  *
  29  * Moves often appear in container implementations. For example, when we append
  30  * to a vector, we may need to resize its buffer. This entails moving each of
  31  * its extant elements from the old, smaller buffer to the new, larger buffer.
  32  * But once the elements have been migrated, we're just going to throw away the
  33  * old buffer; we don't care if they still have their values. So if the vector's
  34  * element type can implement "move" more efficiently than "copy", the vector
  35  * resizing should by all means use a "move" operation. Hash tables also need to
  36  * be resized.
  37  *
  38  * The details of the optimization, and whether it's worth applying, vary from
  39  * one type to the next. And while some constructor calls are moves, many really
  40  * are copies, and can't be optimized this way. So we need:
  41  *
  42  * 1) a way for a particular invocation of a copy constructor to say that it's
  43  *    really a move, and that the value of the original isn't important
  44  *    afterwards (although it must still be safe to destroy); and
  45  *
  46  * 2) a way for a type (like Vector) to announce that it can be moved more
  47  *    efficiently than it can be copied, and provide an implementation of that
  48  *    move operation.
  49  *
  50  * The Move(T&) function takes a reference to a T, and returns a MoveRef<T>
  51  * referring to the same value; that's 1). A MoveRef<T> is simply a reference
  52  * to a T, annotated to say that a copy constructor applied to it may move that
  53  * T, instead of copying it. Finally, a constructor that accepts an MoveRef<T>
  54  * should perform a more efficient move, instead of a copy, providing 2).
  55  *
  56  * So, where we might define a copy constructor for a class C like this:
  57  *
  58  *   C(const C& rhs) { ... copy rhs to this ... }
  59  *
  60  * we would declare a move constructor like this:
  61  *
  62  *   C(MoveRef<C> rhs) { ... move rhs to this ... }
  63  *
  64  * And where we might perform a copy like this:
  65  *
  66  *   C c2(c1);
  67  *
  68  * we would perform a move like this:
  69  *
  70  *   C c2(Move(c1))
  71  *
  72  * Note that MoveRef<T> implicitly converts to T&, so you can pass a MoveRef<T>
  73  * to an ordinary copy constructor for a type that doesn't support a special
  74  * move constructor, and you'll just get a copy.  This means that templates can
  75  * use Move whenever they know they won't use the original value any more, even
  76  * if they're not sure whether the type at hand has a specialized move
  77  * constructor.  If it doesn't, the MoveRef<T> will just convert to a T&, and
  78  * the ordinary copy constructor will apply.
  79  *
  80  * A class with a move constructor can also provide a move assignment operator,
  81  * which runs this's destructor, and then applies the move constructor to
  82  * *this's memory. A typical definition:
  83  *
  84  *   C& operator=(MoveRef<C> rhs) {
  85  *     this->~C();
  86  *     new(this) C(rhs);
  87  *     return *this;
  88  *   }
  89  *
  90  * With that in place, one can write move assignments like this:
  91  *
  92  *   c2 = Move(c1);
  93  *
  94  * This destroys c1, moves c1's value to c2, and leaves c1 in an undefined but
  95  * destructible state.
  96  *
  97  * This header file defines MoveRef and Move in the mozilla namespace.  It's up
  98  * to individual containers to annotate moves as such, by calling Move; and it's
  99  * up to individual types to define move constructors.
 100  *
 101  * One hint: if you're writing a move constructor where the type has members
 102  * that should be moved themselves, it's much nicer to write this:
 103  *
 104  *   C(MoveRef<C> c) : x(c->x), y(c->y) { }
 105  *
 106  * than the equivalent:
 107  *
 108  *   C(MoveRef<C> c) { new(&x) X(c->x); new(&y) Y(c->y); }
 109  *
 110  * especially since GNU C++ fails to notice that this does indeed initialize x
 111  * and y, which may matter if they're const.
 112  */
 113 template<typename T>
 114 class MoveRef
 115 {
 116     T* pointer;
 117
 118   public:
 119     explicit MoveRef(T& t) : pointer(&t) { }
 120     T& operator*() const { return *pointer; }
 121     T* operator->() const { return pointer; }
 122     operator T& () const { return *pointer; }
 123 };
 124
 125 template<typename T>
 126 inline MoveRef<T>
 127 Move(T& t)
 128 {
 129   return MoveRef<T>(t);
 130 }
 131
 132 template<typename T>
 133 inline MoveRef<T>
 134 Move(const T& t)
 135 {
 136   return MoveRef<T>(const_cast<T&>(t));
 137 }
 138
 139 /** Swap |t| and |u| using move-construction if possible. */
 140 template<typename T>
 141 inline void
 142 Swap(T& t, T& u)
 143 {
 144   T tmp(Move(t));
 145   t = Move(u);
 146   u = Move(tmp);
 147 }
 148
 149 } // namespace mozilla
 150
 151 #endif // mozilla_Move_h_