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