ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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 |
jhawkins@chromium.org | f8659b7 | 2012-03-06 11:13:10 +0900 | [diff] [blame] | 21 | // * Returned from a function |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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" |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 72 | // * a user-defined conversion "operator RValue()" |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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 ... |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 95 | // Foo(RValue other); // Move constructor. |
| 96 | // Foo& operator=(RValue rhs); // Move operator= |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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 | // |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 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. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 117 | // |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 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. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 123 | // |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 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 |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 128 | // of never creating a temporary RValue struct even with optimizations |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 129 | // disabled. Also, by virtue of inheritance you can treat the RValue |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 130 | // reference as if it were the move-only type itself. Unfortunately, |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 131 | // using the result of this reinterpret_cast<> is actually undefined behavior |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 132 | // due to C++98 5.2.10.7. In certain compilers (e.g., NaCl) the optimizer |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 133 | // will generate non-working code. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 134 | // |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 135 | // In optimized builds, both implementations generate the same assembly so we |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 136 | // choose the one that adheres to the standard. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 137 | // |
| 138 | // |
kinuko@chromium.org | 288f27a | 2013-10-22 18:18:20 +0900 | [diff] [blame] | 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 | // |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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 |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 157 | // impossible to make a function "void Foo(scoped_ptr<Parent> p)" accept a |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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 | // |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 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. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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() |
sergeygs@chromium.org | eb26917 | 2013-03-06 13:22:58 +0900 | [diff] [blame] | 190 | // would require the RValue struct to be public. |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 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: \ |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 206 | struct rvalue_type { \ |
dcheng@chromium.org | fc6088b | 2013-02-02 17:26:30 +0900 | [diff] [blame] | 207 | explicit rvalue_type(type* object) : object(object) {} \ |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 208 | type* object; \ |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 209 | }; \ |
| 210 | type(type&); \ |
| 211 | void operator=(type&); \ |
| 212 | public: \ |
ajwong@chromium.org | ca5925f | 2012-10-16 05:36:05 +0900 | [diff] [blame] | 213 | operator rvalue_type() { return rvalue_type(this); } \ |
| 214 | type Pass() { return type(rvalue_type(this)); } \ |
kinuko@chromium.org | 288f27a | 2013-10-22 18:18:20 +0900 | [diff] [blame] | 215 | typedef void MoveOnlyTypeForCPP03; \ |
ajwong@chromium.org | 59f1fbb | 2012-01-20 09:03:45 +0900 | [diff] [blame] | 216 | private: |
| 217 | |
| 218 | #endif // BASE_MOVE_H_ |