| 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 #include "base/compiler_specific.h" | |
| 9 | |
| 10 // Macro with the boilerplate that makes a type move-only in C++03. | |
| 11 // | |
| 12 // USAGE | |
| 13 // | |
| 14 // This macro should be used instead of DISALLOW_COPY_AND_ASSIGN to create | |
| 15 // a "move-only" type. Unlike DISALLOW_COPY_AND_ASSIGN, this macro should be | |
| 16 // the first line in a class declaration. | |
| 17 // | |
| 18 // A class using this macro must call .Pass() (or somehow be an r-value already) | |
| 19 // before it can be: | |
| 20 // | |
| 21 // * Passed as a function argument | |
| 22 // * Used as the right-hand side of an assignment | |
| 23 // * Returned from a function | |
| 24 // | |
| 25 // Each class will still need to define their own "move constructor" and "move | |
| 26 // operator=" to make this useful. Here's an example of the macro, the move | |
| 27 // constructor, and the move operator= from the scoped_ptr class: | |
| 28 // | |
| 29 // template <typename T> | |
| 30 // class scoped_ptr { | |
| 31 // MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue) | |
| 32 // public: | |
| 33 // scoped_ptr(RValue& other) : ptr_(other.release()) { } | |
| 34 // scoped_ptr& operator=(RValue& other) { | |
| 35 // swap(other); | |
| 36 // return *this; | |
| 37 // } | |
| 38 // }; | |
| 39 // | |
| 40 // Note that the constructor must NOT be marked explicit. | |
| 41 // | |
| 42 // For consistency, the second parameter to the macro should always be RValue | |
| 43 // unless you have a strong reason to do otherwise. It is only exposed as a | |
| 44 // macro parameter so that the move constructor and move operator= don't look | |
| 45 // like they're using a phantom type. | |
| 46 // | |
| 47 // | |
| 48 // HOW THIS WORKS | |
| 49 // | |
| 50 // For a thorough explanation of this technique, see: | |
| 51 // | |
| 52 // http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Move_Constructor | |
| 53 // | |
| 54 // The summary is that we take advantage of 2 properties: | |
| 55 // | |
| 56 // 1) non-const references will not bind to r-values. | |
| 57 // 2) C++ can apply one user-defined conversion when initializing a | |
| 58 // variable. | |
| 59 // | |
| 60 // The first lets us disable the copy constructor and assignment operator | |
| 61 // by declaring private version of them with a non-const reference parameter. | |
| 62 // | |
| 63 // For l-values, direct initialization still fails like in | |
| 64 // DISALLOW_COPY_AND_ASSIGN because the copy constructor and assignment | |
| 65 // operators are private. | |
| 66 // | |
| 67 // For r-values, the situation is different. The copy constructor and | |
| 68 // assignment operator are not viable due to (1), so we are trying to call | |
| 69 // a non-existent constructor and non-existing operator= rather than a private | |
| 70 // one. Since we have not committed an error quite yet, we can provide an | |
| 71 // alternate conversion sequence and a constructor. We add | |
| 72 // | |
| 73 // * a private struct named "RValue" | |
| 74 // * a user-defined conversion "operator RValue()" | |
| 75 // * a "move constructor" and "move operator=" that take the RValue& as | |
| 76 // their sole parameter. | |
| 77 // | |
| 78 // Only r-values will trigger this sequence and execute our "move constructor" | |
| 79 // or "move operator=." L-values will match the private copy constructor and | |
| 80 // operator= first giving a "private in this context" error. This combination | |
| 81 // gives us a move-only type. | |
| 82 // | |
| 83 // For signaling a destructive transfer of data from an l-value, we provide a | |
| 84 // method named Pass() which creates an r-value for the current instance | |
| 85 // triggering the move constructor or move operator=. | |
| 86 // | |
| 87 // Other ways to get r-values is to use the result of an expression like a | |
| 88 // function call. | |
| 89 // | |
| 90 // Here's an example with comments explaining what gets triggered where: | |
| 91 // | |
| 92 // class Foo { | |
| 93 // MOVE_ONLY_TYPE_FOR_CPP_03(Foo, RValue); | |
| 94 // | |
| 95 // public: | |
| 96 // ... API ... | |
| 97 // Foo(RValue other); // Move constructor. | |
| 98 // Foo& operator=(RValue rhs); // Move operator= | |
| 99 // }; | |
| 100 // | |
| 101 // Foo MakeFoo(); // Function that returns a Foo. | |
| 102 // | |
| 103 // Foo f; | |
| 104 // Foo f_copy(f); // ERROR: Foo(Foo&) is private in this context. | |
| 105 // Foo f_assign; | |
| 106 // f_assign = f; // ERROR: operator=(Foo&) is private in this context. | |
| 107 // | |
| 108 // | |
| 109 // Foo f(MakeFoo()); // R-value so alternate conversion executed. | |
| 110 // Foo f_copy(f.Pass()); // R-value so alternate conversion executed. | |
| 111 // f = f_copy.Pass(); // R-value so alternate conversion executed. | |
| 112 // | |
| 113 // | |
| 114 // IMPLEMENTATION SUBTLETIES WITH RValue | |
| 115 // | |
| 116 // The RValue struct is just a container for a pointer back to the original | |
| 117 // object. It should only ever be created as a temporary, and no external | |
| 118 // class should ever declare it or use it in a parameter. | |
| 119 // | |
| 120 // It is tempting to want to use the RValue type in function parameters, but | |
| 121 // excluding the limited usage here for the move constructor and move | |
| 122 // operator=, doing so would mean that the function could take both r-values | |
| 123 // and l-values equially which is unexpected. See COMPARED To Boost.Move for | |
| 124 // more details. | |
| 125 // | |
| 126 // An alternate, and incorrect, implementation of the RValue class used by | |
| 127 // Boost.Move makes RValue a fieldless child of the move-only type. RValue& | |
| 128 // is then used in place of RValue in the various operators. The RValue& is | |
| 129 // "created" by doing *reinterpret_cast<RValue*>(this). This has the appeal | |
| 130 // of never creating a temporary RValue struct even with optimizations | |
| 131 // disabled. Also, by virtue of inheritance you can treat the RValue | |
| 132 // reference as if it were the move-only type itself. Unfortunately, | |
| 133 // using the result of this reinterpret_cast<> is actually undefined behavior | |
| 134 // due to C++98 5.2.10.7. In certain compilers (e.g., NaCl) the optimizer | |
| 135 // will generate non-working code. | |
| 136 // | |
| 137 // In optimized builds, both implementations generate the same assembly so we | |
| 138 // choose the one that adheres to the standard. | |
| 139 // | |
| 140 // | |
| 141 // WHY HAVE typedef void MoveOnlyTypeForCPP03 | |
| 142 // | |
| 143 // Callback<>/Bind() needs to understand movable-but-not-copyable semantics | |
| 144 // to call .Pass() appropriately when it is expected to transfer the value. | |
| 145 // The cryptic typedef MoveOnlyTypeForCPP03 is added to make this check | |
| 146 // easy and automatic in helper templates for Callback<>/Bind(). | |
| 147 // See IsMoveOnlyType template and its usage in base/callback_internal.h | |
| 148 // for more details. | |
| 149 // | |
| 150 // | |
| 151 // COMPARED TO C++11 | |
| 152 // | |
| 153 // In C++11, you would implement this functionality using an r-value reference | |
| 154 // and our .Pass() method would be replaced with a call to std::move(). | |
| 155 // | |
| 156 // This emulation also has a deficiency where it uses up the single | |
| 157 // user-defined conversion allowed by C++ during initialization. This can | |
| 158 // cause problems in some API edge cases. For instance, in scoped_ptr, it is | |
| 159 // impossible to make a function "void Foo(scoped_ptr<Parent> p)" accept a | |
| 160 // value of type scoped_ptr<Child> even if you add a constructor to | |
| 161 // scoped_ptr<> that would make it look like it should work. C++11 does not | |
| 162 // have this deficiency. | |
| 163 // | |
| 164 // | |
| 165 // COMPARED TO Boost.Move | |
| 166 // | |
| 167 // Our implementation similar to Boost.Move, but we keep the RValue struct | |
| 168 // private to the move-only type, and we don't use the reinterpret_cast<> hack. | |
| 169 // | |
| 170 // In Boost.Move, RValue is the boost::rv<> template. This type can be used | |
| 171 // when writing APIs like: | |
| 172 // | |
| 173 // void MyFunc(boost::rv<Foo>& f) | |
| 174 // | |
| 175 // that can take advantage of rv<> to avoid extra copies of a type. However you | |
| 176 // would still be able to call this version of MyFunc with an l-value: | |
| 177 // | |
| 178 // Foo f; | |
| 179 // MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass(). | |
| 180 // | |
| 181 // unless someone is very careful to also declare a parallel override like: | |
| 182 // | |
| 183 // void MyFunc(const Foo& f) | |
| 184 // | |
| 185 // that would catch the l-values first. This was declared unsafe in C++11 and | |
| 186 // a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot | |
| 187 // ensure this in C++03. | |
| 188 // | |
| 189 // Since we have no need for writing such APIs yet, our implementation keeps | |
| 190 // RValue private and uses a .Pass() method to do the conversion instead of | |
| 191 // trying to write a version of "std::move()." Writing an API like std::move() | |
| 192 // would require the RValue struct to be public. | |
| 193 // | |
| 194 // | |
| 195 // CAVEATS | |
| 196 // | |
| 197 // If you include a move-only type as a field inside a class that does not | |
| 198 // explicitly declare a copy constructor, the containing class's implicit | |
| 199 // copy constructor will change from Containing(const Containing&) to | |
| 200 // Containing(Containing&). This can cause some unexpected errors. | |
| 201 // | |
| 202 // http://llvm.org/bugs/show_bug.cgi?id=11528 | |
| 203 // | |
| 204 // The workaround is to explicitly declare your copy constructor. | |
| 205 // | |
| 206 #define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \ | |
| 207 private: \ | |
| 208 struct rvalue_type { \ | |
| 209 explicit rvalue_type(type* object) : object(object) {} \ | |
| 210 type* object; \ | |
| 211 }; \ | |
| 212 type(type&); \ | |
| 213 void operator=(type&); \ | |
| 214 public: \ | |
| 215 operator rvalue_type() { return rvalue_type(this); } \ | |
| 216 type Pass() WARN_UNUSED_RESULT { return type(rvalue_type(this)); } \ | |
| 217 typedef void MoveOnlyTypeForCPP03; \ | |
| 218 private: | |
| 219 | |
| 220 #define MOVE_ONLY_TYPE_WITH_MOVE_CONSTRUCTOR_FOR_CPP_03(type) \ | |
| 221 private: \ | |
| 222 type(const type&); \ | |
| 223 void operator=(const type&); \ | |
| 224 public: \ | |
| 225 type&& Pass() WARN_UNUSED_RESULT { return static_cast<type&&>(*this); } \ | |
| 226 typedef void MoveOnlyTypeForCPP03; \ | |
| 227 private: | |
| 228 | |
| 229 #define TYPE_WITH_MOVE_CONSTRUCTOR_FOR_CPP_03(type) \ | |
| 230 public: \ | |
| 231 type&& Pass() WARN_UNUSED_RESULT { return static_cast<type&&>(*this); } \ | |
| 232 private: | |
| 233 | |
| 234 #endif // BASE_MOVE_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
