michael@0: // Copyright (c) 2012 The Chromium Authors. All rights reserved. michael@0: // Use of this source code is governed by a BSD-style license that can be michael@0: // found in the LICENSE file. michael@0: michael@0: #ifndef BASE_MOVE_H_ michael@0: #define BASE_MOVE_H_ michael@0: michael@0: // Macro with the boilerplate that makes a type move-only in C++03. michael@0: // michael@0: // USAGE michael@0: // michael@0: // This macro should be used instead of DISALLOW_COPY_AND_ASSIGN to create michael@0: // a "move-only" type. Unlike DISALLOW_COPY_AND_ASSIGN, this macro should be michael@0: // the first line in a class declaration. michael@0: // michael@0: // A class using this macro must call .Pass() (or somehow be an r-value already) michael@0: // before it can be: michael@0: // michael@0: // * Passed as a function argument michael@0: // * Used as the right-hand side of an assignment michael@0: // * Returned from a function michael@0: // michael@0: // Each class will still need to define their own "move constructor" and "move michael@0: // operator=" to make this useful. Here's an example of the macro, the move michael@0: // constructor, and the move operator= from the scoped_ptr class: michael@0: // michael@0: // template michael@0: // class scoped_ptr { michael@0: // MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue) michael@0: // public: michael@0: // scoped_ptr(RValue& other) : ptr_(other.release()) { } michael@0: // scoped_ptr& operator=(RValue& other) { michael@0: // swap(other); michael@0: // return *this; michael@0: // } michael@0: // }; michael@0: // michael@0: // Note that the constructor must NOT be marked explicit. michael@0: // michael@0: // For consistency, the second parameter to the macro should always be RValue michael@0: // unless you have a strong reason to do otherwise. It is only exposed as a michael@0: // macro parameter so that the move constructor and move operator= don't look michael@0: // like they're using a phantom type. michael@0: // michael@0: // michael@0: // HOW THIS WORKS michael@0: // michael@0: // For a thorough explanation of this technique, see: michael@0: // michael@0: // http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Move_Constructor michael@0: // michael@0: // The summary is that we take advantage of 2 properties: michael@0: // michael@0: // 1) non-const references will not bind to r-values. michael@0: // 2) C++ can apply one user-defined conversion when initializing a michael@0: // variable. michael@0: // michael@0: // The first lets us disable the copy constructor and assignment operator michael@0: // by declaring private version of them with a non-const reference parameter. michael@0: // michael@0: // For l-values, direct initialization still fails like in michael@0: // DISALLOW_COPY_AND_ASSIGN because the copy constructor and assignment michael@0: // operators are private. michael@0: // michael@0: // For r-values, the situation is different. The copy constructor and michael@0: // assignment operator are not viable due to (1), so we are trying to call michael@0: // a non-existent constructor and non-existing operator= rather than a private michael@0: // one. Since we have not committed an error quite yet, we can provide an michael@0: // alternate conversion sequence and a constructor. We add michael@0: // michael@0: // * a private struct named "RValue" michael@0: // * a user-defined conversion "operator RValue()" michael@0: // * a "move constructor" and "move operator=" that take the RValue& as michael@0: // their sole parameter. michael@0: // michael@0: // Only r-values will trigger this sequence and execute our "move constructor" michael@0: // or "move operator=." L-values will match the private copy constructor and michael@0: // operator= first giving a "private in this context" error. This combination michael@0: // gives us a move-only type. michael@0: // michael@0: // For signaling a destructive transfer of data from an l-value, we provide a michael@0: // method named Pass() which creates an r-value for the current instance michael@0: // triggering the move constructor or move operator=. michael@0: // michael@0: // Other ways to get r-values is to use the result of an expression like a michael@0: // function call. michael@0: // michael@0: // Here's an example with comments explaining what gets triggered where: michael@0: // michael@0: // class Foo { michael@0: // MOVE_ONLY_TYPE_FOR_CPP_03(Foo, RValue); michael@0: // michael@0: // public: michael@0: // ... API ... michael@0: // Foo(RValue other); // Move constructor. michael@0: // Foo& operator=(RValue rhs); // Move operator= michael@0: // }; michael@0: // michael@0: // Foo MakeFoo(); // Function that returns a Foo. michael@0: // michael@0: // Foo f; michael@0: // Foo f_copy(f); // ERROR: Foo(Foo&) is private in this context. michael@0: // Foo f_assign; michael@0: // f_assign = f; // ERROR: operator=(Foo&) is private in this context. michael@0: // michael@0: // michael@0: // Foo f(MakeFoo()); // R-value so alternate conversion executed. michael@0: // Foo f_copy(f.Pass()); // R-value so alternate conversion executed. michael@0: // f = f_copy.Pass(); // R-value so alternate conversion executed. michael@0: // michael@0: // michael@0: // IMPLEMENTATION SUBTLETIES WITH RValue michael@0: // michael@0: // The RValue struct is just a container for a pointer back to the original michael@0: // object. It should only ever be created as a temporary, and no external michael@0: // class should ever declare it or use it in a parameter. michael@0: // michael@0: // It is tempting to want to use the RValue type in function parameters, but michael@0: // excluding the limited usage here for the move constructor and move michael@0: // operator=, doing so would mean that the function could take both r-values michael@0: // and l-values equially which is unexpected. See COMPARED To Boost.Move for michael@0: // more details. michael@0: // michael@0: // An alternate, and incorrect, implementation of the RValue class used by michael@0: // Boost.Move makes RValue a fieldless child of the move-only type. RValue& michael@0: // is then used in place of RValue in the various operators. The RValue& is michael@0: // "created" by doing *reinterpret_cast(this). This has the appeal michael@0: // of never creating a temporary RValue struct even with optimizations michael@0: // disabled. Also, by virtue of inheritance you can treat the RValue michael@0: // reference as if it were the move-only type itself. Unfortunately, michael@0: // using the result of this reinterpret_cast<> is actually undefined behavior michael@0: // due to C++98 5.2.10.7. In certain compilers (e.g., NaCl) the optimizer michael@0: // will generate non-working code. michael@0: // michael@0: // In optimized builds, both implementations generate the same assembly so we michael@0: // choose the one that adheres to the standard. michael@0: // michael@0: // michael@0: // COMPARED TO C++11 michael@0: // michael@0: // In C++11, you would implement this functionality using an r-value reference michael@0: // and our .Pass() method would be replaced with a call to std::move(). michael@0: // michael@0: // This emulation also has a deficiency where it uses up the single michael@0: // user-defined conversion allowed by C++ during initialization. This can michael@0: // cause problems in some API edge cases. For instance, in scoped_ptr, it is michael@0: // impossible to make a function "void Foo(scoped_ptr p)" accept a michael@0: // value of type scoped_ptr even if you add a constructor to michael@0: // scoped_ptr<> that would make it look like it should work. C++11 does not michael@0: // have this deficiency. michael@0: // michael@0: // michael@0: // COMPARED TO Boost.Move michael@0: // michael@0: // Our implementation similar to Boost.Move, but we keep the RValue struct michael@0: // private to the move-only type, and we don't use the reinterpret_cast<> hack. michael@0: // michael@0: // In Boost.Move, RValue is the boost::rv<> template. This type can be used michael@0: // when writing APIs like: michael@0: // michael@0: // void MyFunc(boost::rv& f) michael@0: // michael@0: // that can take advantage of rv<> to avoid extra copies of a type. However you michael@0: // would still be able to call this version of MyFunc with an l-value: michael@0: // michael@0: // Foo f; michael@0: // MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass(). michael@0: // michael@0: // unless someone is very careful to also declare a parallel override like: michael@0: // michael@0: // void MyFunc(const Foo& f) michael@0: // michael@0: // that would catch the l-values first. This was declared unsafe in C++11 and michael@0: // a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot michael@0: // ensure this in C++03. michael@0: // michael@0: // Since we have no need for writing such APIs yet, our implementation keeps michael@0: // RValue private and uses a .Pass() method to do the conversion instead of michael@0: // trying to write a version of "std::move()." Writing an API like std::move() michael@0: // would require the RValue struct to be public. michael@0: // michael@0: // michael@0: // CAVEATS michael@0: // michael@0: // If you include a move-only type as a field inside a class that does not michael@0: // explicitly declare a copy constructor, the containing class's implicit michael@0: // copy constructor will change from Containing(const Containing&) to michael@0: // Containing(Containing&). This can cause some unexpected errors. michael@0: // michael@0: // http://llvm.org/bugs/show_bug.cgi?id=11528 michael@0: // michael@0: // The workaround is to explicitly declare your copy constructor. michael@0: // michael@0: #define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \ michael@0: private: \ michael@0: struct rvalue_type { \ michael@0: explicit rvalue_type(type* object) : object(object) {} \ michael@0: type* object; \ michael@0: }; \ michael@0: type(type&); \ michael@0: void operator=(type&); \ michael@0: public: \ michael@0: operator rvalue_type() { return rvalue_type(this); } \ michael@0: type Pass() { return type(rvalue_type(this)); } \ michael@0: private: michael@0: michael@0: #endif // BASE_MOVE_H_