Gan likun / mbed-dev

00

platform/NonCopyable.h@0:13413ea9a877, 2022-06-12 (annotated)

Committer:
ganlikun
Date:
Sun Jun 12 14:02:44 2022 +0000
Revision:
0:13413ea9a877
00

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ganlikun 0:13413ea9a877 1 /* Copyright (c) 2017 ARM Limited
ganlikun 0:13413ea9a877 2 *
ganlikun 0:13413ea9a877 3 * Licensed under the Apache License, Version 2.0 (the "License");
ganlikun 0:13413ea9a877 4 * you may not use this file except in compliance with the License.
ganlikun 0:13413ea9a877 5 * You may obtain a copy of the License at
ganlikun 0:13413ea9a877 6 *
ganlikun 0:13413ea9a877 7 * http://www.apache.org/licenses/LICENSE-2.0
ganlikun 0:13413ea9a877 8 *
ganlikun 0:13413ea9a877 9 * Unless required by applicable law or agreed to in writing, software
ganlikun 0:13413ea9a877 10 * distributed under the License is distributed on an "AS IS" BASIS,
ganlikun 0:13413ea9a877 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ganlikun 0:13413ea9a877 12 * See the License for the specific language governing permissions and
ganlikun 0:13413ea9a877 13 * limitations under the License.
ganlikun 0:13413ea9a877 14 */
ganlikun 0:13413ea9a877 15
ganlikun 0:13413ea9a877 16 #ifndef MBED_NONCOPYABLE_H_
ganlikun 0:13413ea9a877 17 #define MBED_NONCOPYABLE_H_
ganlikun 0:13413ea9a877 18
ganlikun 0:13413ea9a877 19 namespace mbed {
ganlikun 0:13413ea9a877 20
ganlikun 0:13413ea9a877 21 /**
ganlikun 0:13413ea9a877 22 * Inheriting from this class autogeneration of copy construction and copy
ganlikun 0:13413ea9a877 23 * assignement operations.
ganlikun 0:13413ea9a877 24 *
ganlikun 0:13413ea9a877 25 * Classes which are not value type should inherit privately from this class
ganlikun 0:13413ea9a877 26 * to avoid generation of invalid copy constructor or copy assignement operator
ganlikun 0:13413ea9a877 27 * which can lead to unoticeable programming errors.
ganlikun 0:13413ea9a877 28 *
ganlikun 0:13413ea9a877 29 * As an example consider the following signature:
ganlikun 0:13413ea9a877 30 *
ganlikun 0:13413ea9a877 31 * @code
ganlikun 0:13413ea9a877 32 * class Resource;
ganlikun 0:13413ea9a877 33 *
ganlikun 0:13413ea9a877 34 * class Foo {
ganlikun 0:13413ea9a877 35 * public:
ganlikun 0:13413ea9a877 36 * Foo() : _resource(new Resource()) { }
ganlikun 0:13413ea9a877 37 * ~Foo() { delete _resource; }
ganlikun 0:13413ea9a877 38 * private:
ganlikun 0:13413ea9a877 39 * Resource* _resource;
ganlikun 0:13413ea9a877 40 * }
ganlikun 0:13413ea9a877 41 *
ganlikun 0:13413ea9a877 42 * Foo get_foo();
ganlikun 0:13413ea9a877 43 *
ganlikun 0:13413ea9a877 44 * Foo foo = get_foo();
ganlikun 0:13413ea9a877 45 * @endcode
ganlikun 0:13413ea9a877 46 *
ganlikun 0:13413ea9a877 47 * There is a bug in this function, it returns a temporary value which will be
ganlikun 0:13413ea9a877 48 * byte copied into foo then destroyed. Unfortunately, internaly the Foo class
ganlikun 0:13413ea9a877 49 * manage a pointer to a Resource object. This pointer will be released when the
ganlikun 0:13413ea9a877 50 * temporary is destroyed and foo will manage a pointer to an already released
ganlikun 0:13413ea9a877 51 * Resource.
ganlikun 0:13413ea9a877 52 *
ganlikun 0:13413ea9a877 53 * Two issues has to be fixed in the example above:
ganlikun 0:13413ea9a877 54 * - Function signature has to be changed to reflect the fact that Foo
ganlikun 0:13413ea9a877 55 * instances cannot be copied. In that case accessor should return a
ganlikun 0:13413ea9a877 56 * reference to give access to objects already existing and managed.
ganlikun 0:13413ea9a877 57 * Generator on the other hand should return a pointer to the created object.
ganlikun 0:13413ea9a877 58 *
ganlikun 0:13413ea9a877 59 * @code
ganlikun 0:13413ea9a877 60 * // return a reference to an already managed Foo instance
ganlikun 0:13413ea9a877 61 * Foo& get_foo();
ganlikun 0:13413ea9a877 62 * Foo& foo = get_foo();
ganlikun 0:13413ea9a877 63 *
ganlikun 0:13413ea9a877 64 * // create a new Foo instance
ganlikun 0:13413ea9a877 65 * Foo* make_foo();
ganlikun 0:13413ea9a877 66 * Foo* m = make_foo();
ganlikun 0:13413ea9a877 67 * @endcode
ganlikun 0:13413ea9a877 68 *
ganlikun 0:13413ea9a877 69 * - Copy constructor and copy assignement operator has to be made private
ganlikun 0:13413ea9a877 70 * in the Foo class. It prevents unwanted copy of Foo objects. This can be
ganlikun 0:13413ea9a877 71 * done by declaring copy constructor and copy assignement in the private
ganlikun 0:13413ea9a877 72 * section of the Foo class.
ganlikun 0:13413ea9a877 73 *
ganlikun 0:13413ea9a877 74 * @code
ganlikun 0:13413ea9a877 75 * class Foo {
ganlikun 0:13413ea9a877 76 * public:
ganlikun 0:13413ea9a877 77 * Foo() : _resource(new Resource()) { }
ganlikun 0:13413ea9a877 78 * ~Foo() { delete _resource; }
ganlikun 0:13413ea9a877 79 * private:
ganlikun 0:13413ea9a877 80 * // disallow copy operations
ganlikun 0:13413ea9a877 81 * Foo(const Foo&);
ganlikun 0:13413ea9a877 82 * Foo& operator=(const Foo&);
ganlikun 0:13413ea9a877 83 * // data members
ganlikun 0:13413ea9a877 84 * Resource* _resource;
ganlikun 0:13413ea9a877 85 * }
ganlikun 0:13413ea9a877 86 * @endcode
ganlikun 0:13413ea9a877 87 *
ganlikun 0:13413ea9a877 88 * Another solution is to inherit privately from the NonCopyable class.
ganlikun 0:13413ea9a877 89 * It reduces the boiler plate needed to avoid copy operations but more
ganlikun 0:13413ea9a877 90 * importantly it clarifies the programer intent and the object semantic.
ganlikun 0:13413ea9a877 91 *
ganlikun 0:13413ea9a877 92 * class Foo : private NonCopyable<Foo> {
ganlikun 0:13413ea9a877 93 * public:
ganlikun 0:13413ea9a877 94 * Foo() : _resource(new Resource()) { }
ganlikun 0:13413ea9a877 95 * ~Foo() { delete _resource; }
ganlikun 0:13413ea9a877 96 * private:
ganlikun 0:13413ea9a877 97 * Resource* _resource;
ganlikun 0:13413ea9a877 98 * }
ganlikun 0:13413ea9a877 99 *
ganlikun 0:13413ea9a877 100 * @tparam T The type that should be made non copyable. It prevent cases where
ganlikun 0:13413ea9a877 101 * the empty base optimization cannot be applied and therefore ensure that the
ganlikun 0:13413ea9a877 102 * cost of this semantic sugar is null.
ganlikun 0:13413ea9a877 103 *
ganlikun 0:13413ea9a877 104 * As an example, the empty base optimization is prohibited if one of the empty
ganlikun 0:13413ea9a877 105 * base class is also a base type of the first non static data member:
ganlikun 0:13413ea9a877 106 *
ganlikun 0:13413ea9a877 107 * @code
ganlikun 0:13413ea9a877 108 * struct A { };
ganlikun 0:13413ea9a877 109 * struct B : A {
ganlikun 0:13413ea9a877 110 * int foo;
ganlikun 0:13413ea9a877 111 * };
ganlikun 0:13413ea9a877 112 * // thanks to empty base optimization, sizeof(B) == sizeof(int)
ganlikun 0:13413ea9a877 113 *
ganlikun 0:13413ea9a877 114 * struct C : A {
ganlikun 0:13413ea9a877 115 * B b;
ganlikun 0:13413ea9a877 116 * };
ganlikun 0:13413ea9a877 117 *
ganlikun 0:13413ea9a877 118 * // empty base optimization cannot be applied here because A from C and A from
ganlikun 0:13413ea9a877 119 * // B shall have a different address. In that case, with the alignement
ganlikun 0:13413ea9a877 120 * // sizeof(C) == 2* sizeof(int)
ganlikun 0:13413ea9a877 121 * @endcode
ganlikun 0:13413ea9a877 122 *
ganlikun 0:13413ea9a877 123 * The solution to that problem is to templatize the empty class to makes it
ganlikun 0:13413ea9a877 124 * unique to the type it is applied to:
ganlikun 0:13413ea9a877 125 *
ganlikun 0:13413ea9a877 126 * @code
ganlikun 0:13413ea9a877 127 * template<typename T>
ganlikun 0:13413ea9a877 128 * struct A<T> { };
ganlikun 0:13413ea9a877 129 * struct B : A<B> {
ganlikun 0:13413ea9a877 130 * int foo;
ganlikun 0:13413ea9a877 131 * };
ganlikun 0:13413ea9a877 132 * struct C : A<C> {
ganlikun 0:13413ea9a877 133 * B b;
ganlikun 0:13413ea9a877 134 * };
ganlikun 0:13413ea9a877 135 *
ganlikun 0:13413ea9a877 136 * // empty base optimization can be applied B and C does not refer to the same
ganlikun 0:13413ea9a877 137 * // kind of A. sizeof(C) == sizeof(B) == sizeof(int).
ganlikun 0:13413ea9a877 138 * @endcode
ganlikun 0:13413ea9a877 139 */
ganlikun 0:13413ea9a877 140 template<typename T>
ganlikun 0:13413ea9a877 141 class NonCopyable {
ganlikun 0:13413ea9a877 142 protected:
ganlikun 0:13413ea9a877 143 /**
ganlikun 0:13413ea9a877 144 * Disalow construction of NonCopyable objects from outside of its hierarchy.
ganlikun 0:13413ea9a877 145 */
ganlikun 0:13413ea9a877 146 NonCopyable() { }
ganlikun 0:13413ea9a877 147 /**
ganlikun 0:13413ea9a877 148 * Disalow destruction of NonCopyable objects from outside of its hierarchy.
ganlikun 0:13413ea9a877 149 */
ganlikun 0:13413ea9a877 150 ~NonCopyable() { }
ganlikun 0:13413ea9a877 151
ganlikun 0:13413ea9a877 152 private:
ganlikun 0:13413ea9a877 153 /**
ganlikun 0:13413ea9a877 154 * Declare copy constructor as private, any attempt to copy construct
ganlikun 0:13413ea9a877 155 * a NonCopyable will fail at compile time.
ganlikun 0:13413ea9a877 156 */
ganlikun 0:13413ea9a877 157 NonCopyable(const NonCopyable&);
ganlikun 0:13413ea9a877 158
ganlikun 0:13413ea9a877 159 /**
ganlikun 0:13413ea9a877 160 * Declare copy assignement operator as private, any attempt to copy assign
ganlikun 0:13413ea9a877 161 * a NonCopyable will fail at compile time.
ganlikun 0:13413ea9a877 162 */
ganlikun 0:13413ea9a877 163 NonCopyable& operator=(const NonCopyable&);
ganlikun 0:13413ea9a877 164 };
ganlikun 0:13413ea9a877 165
ganlikun 0:13413ea9a877 166 } // namespace mbed
ganlikun 0:13413ea9a877 167
ganlikun 0:13413ea9a877 168 #endif /* MBED_NONCOPYABLE_H_ */
ganlikun 0:13413ea9a877 169