Elijah Stanger-Jones / mbed-dev-f303

test

platform/NonCopyable.h@2:4364577b5ad8, 2020-11-09 (annotated)

Committer:
elijahsj
Date:
Mon Nov 09 00:33:19 2020 -0500
Revision:
2:4364577b5ad8
Parent:
1:8a094db1347f 
copied mbed library

Who changed what in which revision?

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