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