move.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
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 temproary 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. Unfortuantely, 131// using the result of this reinterpret_cast<> is actually undefined behavior 132// due to C++98 5.2.10.7. In certain compilers (eg., 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// COMPARED TO C++11 140// 141// In C++11, you would implement this functionality using an r-value reference 142// and our .Pass() method would be replaced with a call to std::move(). 143// 144// This emulation also has a deficiency where it uses up the single 145// user-defined conversion allowed by C++ during initialization. This can 146// cause problems in some API edge cases. For instance, in scoped_ptr, it is 147// impossible to make an function "void Foo(scoped_ptr<Parent> p)" accept a 148// value of type scoped_ptr<Child> even if you add a constructor to 149// scoped_ptr<> that would make it look like it should work. C++11 does not 150// have this deficiency. 151// 152// 153// COMPARED TO Boost.Move 154// 155// Our implementation similar to Boost.Move, but we keep the RValue struct 156// private to the move-only type, and we don't use the reinterpret_cast<> hack. 157// 158// In Boost.Move, RValue is the boost::rv<> template. This type can be used 159// when writing APIs like: 160// 161// void MyFunc(boost::rv<Foo>& f) 162// 163// that can take advantage of rv<> to avoid extra copies of a type. However you 164// would still be able to call this version of MyFunc with an l-value: 165// 166// Foo f; 167// MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass(). 168// 169// unless someone is very careful to also declare a parallel override like: 170// 171// void MyFunc(const Foo& f) 172// 173// that would catch the l-values first. This was declared unsafe in C++11 and 174// a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot 175// ensure this in C++03. 176// 177// Since we have no need for writing such APIs yet, our implementation keeps 178// RValue private and uses a .Pass() method to do the conversion instead of 179// trying to write a version of "std::move()." Writing an API like std::move() 180// would require the RValue structs to be public. 181// 182// 183// CAVEATS 184// 185// If you include a move-only type as a field inside a class that does not 186// explicitly declare a copy constructor, the containing class's implicit 187// copy constructor will change from Containing(const Containing&) to 188// Containing(Containing&). This can cause some unexpected errors. 189// 190// http://llvm.org/bugs/show_bug.cgi?id=11528 191// 192// The workaround is to explicitly declare your copy constructor. 193// 194#define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \ 195 private: \ 196 struct rvalue_type { \ 197 rvalue_type(type* object) : object(object) {} \ 198 type* object; \ 199 }; \ 200 type(type&); \ 201 void operator=(type&); \ 202 public: \ 203 operator rvalue_type() { return rvalue_type(this); } \ 204 type Pass() { return type(rvalue_type(this)); } \ 205 private: 206 207#endif // BASE_MOVE_H_ 208