1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/sandbox/chromium/base/move.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,207 @@
1.4 +// Copyright (c) 2012 The Chromium Authors. All rights reserved.
1.5 +// Use of this source code is governed by a BSD-style license that can be
1.6 +// found in the LICENSE file.
1.7 +
1.8 +#ifndef BASE_MOVE_H_
1.9 +#define BASE_MOVE_H_
1.10 +
1.11 +// Macro with the boilerplate that makes a type move-only in C++03.
1.12 +//
1.13 +// USAGE
1.14 +//
1.15 +// This macro should be used instead of DISALLOW_COPY_AND_ASSIGN to create
1.16 +// a "move-only" type. Unlike DISALLOW_COPY_AND_ASSIGN, this macro should be
1.17 +// the first line in a class declaration.
1.18 +//
1.19 +// A class using this macro must call .Pass() (or somehow be an r-value already)
1.20 +// before it can be:
1.21 +//
1.22 +// * Passed as a function argument
1.23 +// * Used as the right-hand side of an assignment
1.24 +// * Returned from a function
1.25 +//
1.26 +// Each class will still need to define their own "move constructor" and "move
1.27 +// operator=" to make this useful. Here's an example of the macro, the move
1.28 +// constructor, and the move operator= from the scoped_ptr class:
1.29 +//
1.30 +// template <typename T>
1.31 +// class scoped_ptr {
1.32 +// MOVE_ONLY_TYPE_FOR_CPP_03(scoped_ptr, RValue)
1.33 +// public:
1.34 +// scoped_ptr(RValue& other) : ptr_(other.release()) { }
1.35 +// scoped_ptr& operator=(RValue& other) {
1.36 +// swap(other);
1.37 +// return *this;
1.38 +// }
1.39 +// };
1.40 +//
1.41 +// Note that the constructor must NOT be marked explicit.
1.42 +//
1.43 +// For consistency, the second parameter to the macro should always be RValue
1.44 +// unless you have a strong reason to do otherwise. It is only exposed as a
1.45 +// macro parameter so that the move constructor and move operator= don't look
1.46 +// like they're using a phantom type.
1.47 +//
1.48 +//
1.49 +// HOW THIS WORKS
1.50 +//
1.51 +// For a thorough explanation of this technique, see:
1.52 +//
1.53 +// http://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Move_Constructor
1.54 +//
1.55 +// The summary is that we take advantage of 2 properties:
1.56 +//
1.57 +// 1) non-const references will not bind to r-values.
1.58 +// 2) C++ can apply one user-defined conversion when initializing a
1.59 +// variable.
1.60 +//
1.61 +// The first lets us disable the copy constructor and assignment operator
1.62 +// by declaring private version of them with a non-const reference parameter.
1.63 +//
1.64 +// For l-values, direct initialization still fails like in
1.65 +// DISALLOW_COPY_AND_ASSIGN because the copy constructor and assignment
1.66 +// operators are private.
1.67 +//
1.68 +// For r-values, the situation is different. The copy constructor and
1.69 +// assignment operator are not viable due to (1), so we are trying to call
1.70 +// a non-existent constructor and non-existing operator= rather than a private
1.71 +// one. Since we have not committed an error quite yet, we can provide an
1.72 +// alternate conversion sequence and a constructor. We add
1.73 +//
1.74 +// * a private struct named "RValue"
1.75 +// * a user-defined conversion "operator RValue()"
1.76 +// * a "move constructor" and "move operator=" that take the RValue& as
1.77 +// their sole parameter.
1.78 +//
1.79 +// Only r-values will trigger this sequence and execute our "move constructor"
1.80 +// or "move operator=." L-values will match the private copy constructor and
1.81 +// operator= first giving a "private in this context" error. This combination
1.82 +// gives us a move-only type.
1.83 +//
1.84 +// For signaling a destructive transfer of data from an l-value, we provide a
1.85 +// method named Pass() which creates an r-value for the current instance
1.86 +// triggering the move constructor or move operator=.
1.87 +//
1.88 +// Other ways to get r-values is to use the result of an expression like a
1.89 +// function call.
1.90 +//
1.91 +// Here's an example with comments explaining what gets triggered where:
1.92 +//
1.93 +// class Foo {
1.94 +// MOVE_ONLY_TYPE_FOR_CPP_03(Foo, RValue);
1.95 +//
1.96 +// public:
1.97 +// ... API ...
1.98 +// Foo(RValue other); // Move constructor.
1.99 +// Foo& operator=(RValue rhs); // Move operator=
1.100 +// };
1.101 +//
1.102 +// Foo MakeFoo(); // Function that returns a Foo.
1.103 +//
1.104 +// Foo f;
1.105 +// Foo f_copy(f); // ERROR: Foo(Foo&) is private in this context.
1.106 +// Foo f_assign;
1.107 +// f_assign = f; // ERROR: operator=(Foo&) is private in this context.
1.108 +//
1.109 +//
1.110 +// Foo f(MakeFoo()); // R-value so alternate conversion executed.
1.111 +// Foo f_copy(f.Pass()); // R-value so alternate conversion executed.
1.112 +// f = f_copy.Pass(); // R-value so alternate conversion executed.
1.113 +//
1.114 +//
1.115 +// IMPLEMENTATION SUBTLETIES WITH RValue
1.116 +//
1.117 +// The RValue struct is just a container for a pointer back to the original
1.118 +// object. It should only ever be created as a temporary, and no external
1.119 +// class should ever declare it or use it in a parameter.
1.120 +//
1.121 +// It is tempting to want to use the RValue type in function parameters, but
1.122 +// excluding the limited usage here for the move constructor and move
1.123 +// operator=, doing so would mean that the function could take both r-values
1.124 +// and l-values equially which is unexpected. See COMPARED To Boost.Move for
1.125 +// more details.
1.126 +//
1.127 +// An alternate, and incorrect, implementation of the RValue class used by
1.128 +// Boost.Move makes RValue a fieldless child of the move-only type. RValue&
1.129 +// is then used in place of RValue in the various operators. The RValue& is
1.130 +// "created" by doing *reinterpret_cast<RValue*>(this). This has the appeal
1.131 +// of never creating a temporary RValue struct even with optimizations
1.132 +// disabled. Also, by virtue of inheritance you can treat the RValue
1.133 +// reference as if it were the move-only type itself. Unfortunately,
1.134 +// using the result of this reinterpret_cast<> is actually undefined behavior
1.135 +// due to C++98 5.2.10.7. In certain compilers (e.g., NaCl) the optimizer
1.136 +// will generate non-working code.
1.137 +//
1.138 +// In optimized builds, both implementations generate the same assembly so we
1.139 +// choose the one that adheres to the standard.
1.140 +//
1.141 +//
1.142 +// COMPARED TO C++11
1.143 +//
1.144 +// In C++11, you would implement this functionality using an r-value reference
1.145 +// and our .Pass() method would be replaced with a call to std::move().
1.146 +//
1.147 +// This emulation also has a deficiency where it uses up the single
1.148 +// user-defined conversion allowed by C++ during initialization. This can
1.149 +// cause problems in some API edge cases. For instance, in scoped_ptr, it is
1.150 +// impossible to make a function "void Foo(scoped_ptr<Parent> p)" accept a
1.151 +// value of type scoped_ptr<Child> even if you add a constructor to
1.152 +// scoped_ptr<> that would make it look like it should work. C++11 does not
1.153 +// have this deficiency.
1.154 +//
1.155 +//
1.156 +// COMPARED TO Boost.Move
1.157 +//
1.158 +// Our implementation similar to Boost.Move, but we keep the RValue struct
1.159 +// private to the move-only type, and we don't use the reinterpret_cast<> hack.
1.160 +//
1.161 +// In Boost.Move, RValue is the boost::rv<> template. This type can be used
1.162 +// when writing APIs like:
1.163 +//
1.164 +// void MyFunc(boost::rv<Foo>& f)
1.165 +//
1.166 +// that can take advantage of rv<> to avoid extra copies of a type. However you
1.167 +// would still be able to call this version of MyFunc with an l-value:
1.168 +//
1.169 +// Foo f;
1.170 +// MyFunc(f); // Uh oh, we probably just destroyed |f| w/o calling Pass().
1.171 +//
1.172 +// unless someone is very careful to also declare a parallel override like:
1.173 +//
1.174 +// void MyFunc(const Foo& f)
1.175 +//
1.176 +// that would catch the l-values first. This was declared unsafe in C++11 and
1.177 +// a C++11 compiler will explicitly fail MyFunc(f). Unfortunately, we cannot
1.178 +// ensure this in C++03.
1.179 +//
1.180 +// Since we have no need for writing such APIs yet, our implementation keeps
1.181 +// RValue private and uses a .Pass() method to do the conversion instead of
1.182 +// trying to write a version of "std::move()." Writing an API like std::move()
1.183 +// would require the RValue struct to be public.
1.184 +//
1.185 +//
1.186 +// CAVEATS
1.187 +//
1.188 +// If you include a move-only type as a field inside a class that does not
1.189 +// explicitly declare a copy constructor, the containing class's implicit
1.190 +// copy constructor will change from Containing(const Containing&) to
1.191 +// Containing(Containing&). This can cause some unexpected errors.
1.192 +//
1.193 +// http://llvm.org/bugs/show_bug.cgi?id=11528
1.194 +//
1.195 +// The workaround is to explicitly declare your copy constructor.
1.196 +//
1.197 +#define MOVE_ONLY_TYPE_FOR_CPP_03(type, rvalue_type) \
1.198 + private: \
1.199 + struct rvalue_type { \
1.200 + explicit rvalue_type(type* object) : object(object) {} \
1.201 + type* object; \
1.202 + }; \
1.203 + type(type&); \
1.204 + void operator=(type&); \
1.205 + public: \
1.206 + operator rvalue_type() { return rvalue_type(this); } \
1.207 + type Pass() { return type(rvalue_type(this)); } \
1.208 + private:
1.209 +
1.210 +#endif // BASE_MOVE_H_
