OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. |
| 4 |
| 5 #ifndef BASE_MOVE_H_ |
| 6 #define BASE_MOVE_H_ |
| 7 |
| 8 // Macro with the boilerplate that makes a type move-only in C++03. |
| 9 // |
| 10 // USAGE |
| 11 // |
| 12 // This macro should be used instead of DISALLOW_COPY_AND_ASSIGN to create |
| 13 // a "move-only" type. Unlike DISALLOW_COPY_AND_ASSIGN, this macro should be |
| 14 // the first line in a class declaration. |
| 15 // |
| 16 // A class using this macro must call .Pass() (or somehow be an r-value already) |
| 17 // before it can be: |
| 18 // |
| 19 // * Passed as a function argument |
| 20 // * Used as the right-hand side of an assignment |
| 21 // * Return from a function |
| 22 // |
| 23 // Each class will still need to define their own "move constructor" and "move |
| 24 // operator=" to make this useful. Here's an example of the macro, the move |
| 25 // constructor, and the move operator= from the scoped_ptr class: |
| 26 // |
| 27 // template <typename T> |
| 28 // class scoped_ptr { |
| 29 // MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue) |
| 30 // public: |
| 31 // scoped_ptr(RValue& other) : ptr_(other.release()) { } |
| 32 // scoped_ptr& operator=(RValue& other) { |
| 33 // swap(other); |
| 34 // return *this; |
| 35 // } |
| 36 // }; |
| 37 // |
| 38 // Note that the constructor must NOT be marked explicit. |
| 39 // |
| 40 // For consistency, the second parameter to the macro should always be RValue |
| 41 // unless you have a strong reason to do otherwise. It is only exposed as a |
| 42 // macro parameter so that the move constructor and move operator= don't look |
| 43 // like they're using a phantom type. |
| 44 // |
| 45 // |
| 46 // HOW THIS WORKS |
| 47 // |
| 48 // For a thorough explanation of this technique, see: |
| 49 // |
| 50 // http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Move_Constructor |
| 51 // |
| 52 // The summary is that we take advantage of 2 properties: |
| 53 // |
| 54 // 1) non-const references will not bind to r-values. |
| 55 // 2) C++ can apply one user-defined conversion when initializing a |
| 56 // variable. |
| 57 // |
| 58 // The first lets us disable the copy constructor and assignment operator |
| 59 // by declaring private version of them with a non-const reference parameter. |
| 60 // |
| 61 // For l-values, direct initialization still fails like in |
| 62 // DISALLOW_COPY_AND_ASSIGN because the copy constructor and assignment |
| 63 // operators are private. |
| 64 // |
| 65 // For r-values, the situation is different. The copy constructor and |
| 66 // assignment operator are not viable due to (1), so we are trying to call |
| 67 // a non-existent constructor and non-existing operator= rather than a private |
| 68 // one. Since we have not committed an error quite yet, we can provide an |
| 69 // alternate conversion sequence and a constructor. We add |
| 70 // |
| 71 // * a private struct named "RValue" |
| 72 // * a user-defined conversion "operator RValue&()" |
| 73 // * a "move constructor" and "move operator=" that take the RValue& as |
| 74 // their sole parameter. |
| 75 // |
| 76 // Only r-values will trigger this sequence and execute our "move constructor" |
| 77 // or "move operator=." L-values will match the private copy constructor and |
| 78 // operator= first giving a "private in this context" error. This combination |
| 79 // gives us a move-only type. |
| 80 // |
| 81 // For signaling a destructive transfer of data from an l-value, we provide a |
| 82 // method named Pass() which creates an r-value for the current instance |
| 83 // triggering the move constructor or move operator=. |
| 84 // |
| 85 // Other ways to get r-values is to use the result of an expression like a |
| 86 // function call. |
| 87 // |
| 88 // Here's an example with comments explaining what gets triggered where: |
| 89 // |
| 90 // class Foo { |
| 91 // MOVE_ONLY_TYPE_FOR_CPP_03(Foo, RValue); |
| 92 // |
| 93 // public: |
| 94 // ... API ... |
| 95 // Foo(RValue& other); // Move constructor. |
| 96 // Foo& operator=(RValue& rhs); // Move operator= |
| 97 // }; |
| 98 // |
| 99 // Foo MakeFoo(); // Function that returns a Foo. |
| 100 // |
| 101 // Foo f; |
| 102 // Foo f_copy(f); // ERROR: Foo(Foo&) is private in this context. |
| 103 // Foo f_assign; |
| 104 // f_assign = f; // ERROR: operator=(Foo&) is private in this context. |
| 105 // |
| 106 // |
| 107 // Foo f(MakeFoo()); // R-value so alternate conversion executed. |
| 108 // Foo f_copy(f.Pass()); // R-value so alternate conversion executed. |
| 109 // f = f_copy.Pass(); // R-value so alternate conversion executed. |
| 110 // |
| 111 // |
| 112 // IMPLEMENTATION SUBTLETIES WITH RValue |
| 113 // |
| 114 // The RValue struct has subtle properties: |
| 115 // |
| 116 // 1) All its methods are declared, but intentionally not defined. |
| 117 // 2) It is *never* instantiated. |
| 118 // 3) It is a child of the move-only type. |
| 119 // |
| 120 // (1) is a guard against accidental violation of (2). If an instance of |
| 121 // RValue were ever created, either as a temporary, or as a copy to some |
| 122 // function parameter or field of a class, the binary will not link. |
| 123 // |
| 124 // This ensures that RValue can only exist as a temporary which is important |
| 125 // to avoid accidental danging references. |
| 126 // |
| 127 // (3) allows us to get around instantiations because our user-defined |
| 128 // conversion can return a downcast of this pointer. |
| 129 // |
| 130 // operator RValue&() { return *reinterpret_cast<RValue*>(this); } |
| 131 // |
| 132 // Because RValue does not extend the object size or add any virtual methods, |
| 133 // this type-pun is safe. |
| 134 // |
| 135 // An alternative implementation would be to make RValue into a concrete |
| 136 // struct that holds a reference to the type. But in the non-optimized build, |
| 137 // this causes unnecessary temporaries to be made bloating the object files. |
| 138 // Also, it would then be possible to accidentally persist an RValue instance. |
| 139 // |
| 140 // |
| 141 // COMPARED TO C++11 |
| 142 // |
| 143 // In C++11, you would implement this functionality using an r-value reference |
| 144 // and our .Pass() method would be replaced with a call to std::move(). |
| 145 // |
| 146 // This emulation also has a deficiency where it uses up the single |
| 147 // user-defined conversion allowed by C++ during initialization. This can |
| 148 // cause problems in some API edge cases. For instance, in scoped_ptr, it is |
| 149 // impossible to make an function "void Foo(scoped_ptr<Parent> p)" accept a |
| 150 // value of type scoped_ptr<Child> even if you add a constructor to |
| 151 // scoped_ptr<> that would make it look like it should work. C++11 does not |
| 152 // have this deficiency. |
| 153 // |
| 154 // |
| 155 // COMPARED TO Boost.Move |
| 156 // |
| 157 // Our implementation is based on Boost.Move, but we keep the RValue struct |
| 158 // private to the move-only type. |
| 159 // |
| 160 // In Boost.Move, RValue is the boost::rv<> template. This type can be used |
| 161 // when writing APIs like: |
| 162 // |
| 163 // void MyFunc(boost::rv<Foo>& f) |
| 164 // |
| 165 // that can take advantage of rv<> to avoid extra copies of a type. However you |
| 166 // would still be able to call this version of MyFunc with an l-value: |
| 167 // |
| 168 // Foo f; |
| 169 // MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass(). |
| 170 // |
| 171 // unless someone is very careful to also declare a parallel override like: |
| 172 // |
| 173 // void MyFunc(const Foo& f) |
| 174 // |
| 175 // that would catch the l-values first. This was declared unsafe in C++11 and |
| 176 // a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot |
| 177 // ensure this in C++03. |
| 178 // |
| 179 // Since we have no need for writing such APIs yet, our implementation keeps |
| 180 // RValue private and uses a .Pass() method to do the conversion instead of |
| 181 // trying to write a version of "std::move()." Writing an API like std::move() |
| 182 // would require the RValue structs to be public. |
| 183 // |
| 184 // |
| 185 // CAVEATS |
| 186 // |
| 187 // If you include a move-only type as a field inside a class that does not |
| 188 // explicitly declare a copy constructor, the containing class's implicit |
| 189 // copy constructor will change from Containing(const Containing&) to |
| 190 // Containing(Containing&). This can cause some unexpected errors. |
| 191 // |
| 192 // http://llvm.org/bugs/show_bug.cgi?id=11528 |
| 193 // |
| 194 // The workaround is to explicitly declare your copy constructor. |
| 195 // |
| 196 #define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \ |
| 197 private: \ |
| 198 struct rvalue_type : public type { \ |
| 199 rvalue_type(); \ |
| 200 ~rvalue_type(); \ |
| 201 rvalue_type(const rvalue_type&); \ |
| 202 void operator=(const rvalue_type&); \ |
| 203 }; \ |
| 204 type(type&); \ |
| 205 void operator=(type&); \ |
| 206 public: \ |
| 207 operator rvalue_type&() { return *reinterpret_cast<rvalue_type*>(this); } \ |
| 208 type Pass() { return type(*reinterpret_cast<rvalue_type*>(this)); } \ |
| 209 private: |
| 210 |
| 211 #endif // BASE_MOVE_H_ |
OLD | NEW |