Pedro Correia / mbed-dev

mbed library sources. Supersedes mbed-src.

Fork of mbed-dev by mbed official

platform/NonCopyable.h@168:9672193075cf, 2017-07-06 (annotated)

Committer:
AnnaBridge
Date:
Thu Jul 06 15:42:05 2017 +0100
Revision:
168:9672193075cf
Child:
180:96ed750bd169
This updates the lib to the mbed lib v 146

Who changed what in which revision?

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