Takaaki Numai / mbed-dev

inport from local

Dependents:   Hobbyking_Cheetah_0511

platform/NonCopyable.h@0:85b3fd62ea1a, 2020-03-16 (annotated)

Committer:
NYX
Date:
Mon Mar 16 06:35:48 2020 +0000
Revision:
0:85b3fd62ea1a
reinport to mbed;

Who changed what in which revision?

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