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 // * Returned 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 is just a container for a pointer back to the original 115 // object. It should only ever be created as a temporary, and no external 116 // class should ever declare it or use it in a parameter. 117 // 118 // It is tempting to want to use the RValue type in function parameters, but 119 // excluding the limited usage here for the move constructor and move 120 // operator=, doing so would mean that the function could take both r-values 121 // and l-values equially which is unexpected. See COMPARED To Boost.Move for 122 // more details. 123 // 124 // An alternate, and incorrect, implementation of the RValue class used by 125 // Boost.Move makes RValue a fieldless child of the move-only type. RValue& 126 // is then used in place of RValue in the various operators. The RValue& is 127 // "created" by doing *reinterpret_cast<RValue*>(this). This has the appeal 128 // of never creating a temporary RValue struct even with optimizations 129 // disabled. Also, by virtue of inheritance you can treat the RValue 130 // reference as if it were the move-only type itself. Unfortunately, 131 // using the result of this reinterpret_cast<> is actually undefined behavior 132 // due to C++98 5.2.10.7. In certain compilers (e.g., NaCl) the optimizer 133 // will generate non-working code. 134 // 135 // In optimized builds, both implementations generate the same assembly so we 136 // choose the one that adheres to the standard. 137 // 138 // 139 // WHY HAVE typedef void MoveOnlyTypeForCPP03 140 // 141 // Callback<>/Bind() needs to understand movable-but-not-copyable semantics 142 // to call .Pass() appropriately when it is expected to transfer the value. 143 // The cryptic typedef MoveOnlyTypeForCPP03 is added to make this check 144 // easy and automatic in helper templates for Callback<>/Bind(). 145 // See IsMoveOnlyType template and its usage in base/callback_internal.h 146 // for more details. 147 // 148 // 149 // COMPARED TO C++11 150 // 151 // In C++11, you would implement this functionality using an r-value reference 152 // and our .Pass() method would be replaced with a call to std::move(). 153 // 154 // This emulation also has a deficiency where it uses up the single 155 // user-defined conversion allowed by C++ during initialization. This can 156 // cause problems in some API edge cases. For instance, in scoped_ptr, it is 157 // impossible to make a function "void Foo(scoped_ptr<Parent> p)" accept a 158 // value of type scoped_ptr<Child> even if you add a constructor to 159 // scoped_ptr<> that would make it look like it should work. C++11 does not 160 // have this deficiency. 161 // 162 // 163 // COMPARED TO Boost.Move 164 // 165 // Our implementation similar to Boost.Move, but we keep the RValue struct 166 // private to the move-only type, and we don't use the reinterpret_cast<> hack. 167 // 168 // In Boost.Move, RValue is the boost::rv<> template. This type can be used 169 // when writing APIs like: 170 // 171 // void MyFunc(boost::rv<Foo>& f) 172 // 173 // that can take advantage of rv<> to avoid extra copies of a type. However you 174 // would still be able to call this version of MyFunc with an l-value: 175 // 176 // Foo f; 177 // MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass(). 178 // 179 // unless someone is very careful to also declare a parallel override like: 180 // 181 // void MyFunc(const Foo& f) 182 // 183 // that would catch the l-values first. This was declared unsafe in C++11 and 184 // a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot 185 // ensure this in C++03. 186 // 187 // Since we have no need for writing such APIs yet, our implementation keeps 188 // RValue private and uses a .Pass() method to do the conversion instead of 189 // trying to write a version of "std::move()." Writing an API like std::move() 190 // would require the RValue struct to be public. 191 // 192 // 193 // CAVEATS 194 // 195 // If you include a move-only type as a field inside a class that does not 196 // explicitly declare a copy constructor, the containing class's implicit 197 // copy constructor will change from Containing(const Containing&) to 198 // Containing(Containing&). This can cause some unexpected errors. 199 // 200 // http://llvm.org/bugs/show_bug.cgi?id=11528 201 // 202 // The workaround is to explicitly declare your copy constructor. 203 // 204 #define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \ 205 private: \ 206 struct rvalue_type { \ 207 explicit rvalue_type(type* object) : object(object) {} \ 208 type* object; \ 209 }; \ 210 type(type&); \ 211 void operator=(type&); \ 212 public: \ 213 operator rvalue_type() { return rvalue_type(this); } \ 214 type Pass() { return type(rvalue_type(this)); } \ 215 typedef void MoveOnlyTypeForCPP03; \ 216 private: 217 218 #endif // BASE_MOVE_H_ 219