mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

platform/NonCopyable.h@181:57724642e740, 2018-02-16 (annotated)

Committer:
AnnaBridge
Date:
Fri Feb 16 16:09:33 2018 +0000
Revision:
181:57724642e740
Parent:
180:96ed750bd169
Child:
184:08ed48f1de7f
mbed-dev library. Release version 159.

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
Anna Bridge 180:96ed750bd169 19 #if (!defined(MBED_DEBUG) && (MBED_CONF_PLATFORM_FORCE_NON_COPYABLE_ERROR == 0))
Anna Bridge 180:96ed750bd169 20 #include "mbed_toolchain.h"
Anna Bridge 180:96ed750bd169 21 #include "mbed_debug.h"
Anna Bridge 180:96ed750bd169 22 #endif
Anna Bridge 180:96ed750bd169 23
Anna Bridge 180:96ed750bd169 24 namespace mbed {
AnnaBridge 168:9672193075cf 25
AnnaBridge 168:9672193075cf 26 /**
Anna Bridge 180:96ed750bd169 27 * Inheriting from this class autogeneration of copy construction and copy
Anna Bridge 180:96ed750bd169 28 * assignement operations.
Anna Bridge 180:96ed750bd169 29 *
Anna Bridge 180:96ed750bd169 30 * Classes which are not value type should inherit privately from this class
AnnaBridge 168:9672193075cf 31 * to avoid generation of invalid copy constructor or copy assignement operator
Anna Bridge 180:96ed750bd169 32 * which can lead to unoticeable programming errors.
Anna Bridge 180:96ed750bd169 33 *
Anna Bridge 180:96ed750bd169 34 * As an example consider the following signature:
Anna Bridge 180:96ed750bd169 35 *
AnnaBridge 168:9672193075cf 36 * @code
Anna Bridge 180:96ed750bd169 37 * class Resource;
AnnaBridge 168:9672193075cf 38 *
Anna Bridge 180:96ed750bd169 39 * class Foo {
Anna Bridge 180:96ed750bd169 40 * public:
AnnaBridge 168:9672193075cf 41 * Foo() : _resource(new Resource()) { }
Anna Bridge 180:96ed750bd169 42 * ~Foo() { delete _resource; }
AnnaBridge 168:9672193075cf 43 * private:
AnnaBridge 168:9672193075cf 44 * Resource* _resource;
AnnaBridge 168:9672193075cf 45 * }
Anna Bridge 180:96ed750bd169 46 *
AnnaBridge 168:9672193075cf 47 * Foo get_foo();
Anna Bridge 180:96ed750bd169 48 *
AnnaBridge 168:9672193075cf 49 * Foo foo = get_foo();
Anna Bridge 180:96ed750bd169 50 * @endcode
Anna Bridge 180:96ed750bd169 51 *
Anna Bridge 180:96ed750bd169 52 * There is a bug in this function, it returns a temporary value which will be
Anna Bridge 180:96ed750bd169 53 * byte copied into foo then destroyed. Unfortunately, internaly the Foo class
Anna Bridge 180:96ed750bd169 54 * manage a pointer to a Resource object. This pointer will be released when the
Anna Bridge 180:96ed750bd169 55 * temporary is destroyed and foo will manage a pointer to an already released
AnnaBridge 168:9672193075cf 56 * Resource.
Anna Bridge 180:96ed750bd169 57 *
Anna Bridge 180:96ed750bd169 58 * Two issues has to be fixed in the example above:
Anna Bridge 180:96ed750bd169 59 * - Function signature has to be changed to reflect the fact that Foo
Anna Bridge 180:96ed750bd169 60 * instances cannot be copied. In that case accessor should return a
Anna Bridge 180:96ed750bd169 61 * reference to give access to objects already existing and managed.
AnnaBridge 168:9672193075cf 62 * Generator on the other hand should return a pointer to the created object.
Anna Bridge 180:96ed750bd169 63 *
Anna Bridge 180:96ed750bd169 64 * @code
AnnaBridge 168:9672193075cf 65 * // return a reference to an already managed Foo instance
Anna Bridge 180:96ed750bd169 66 * Foo& get_foo();
AnnaBridge 168:9672193075cf 67 * Foo& foo = get_foo();
Anna Bridge 180:96ed750bd169 68 *
AnnaBridge 168:9672193075cf 69 * // create a new Foo instance
AnnaBridge 168:9672193075cf 70 * Foo* make_foo();
AnnaBridge 168:9672193075cf 71 * Foo* m = make_foo();
AnnaBridge 168:9672193075cf 72 * @endcode
Anna Bridge 180:96ed750bd169 73 *
Anna Bridge 180:96ed750bd169 74 * - Copy constructor and copy assignement operator has to be made private
Anna Bridge 180:96ed750bd169 75 * in the Foo class. It prevents unwanted copy of Foo objects. This can be
Anna Bridge 180:96ed750bd169 76 * done by declaring copy constructor and copy assignement in the private
AnnaBridge 168:9672193075cf 77 * section of the Foo class.
Anna Bridge 180:96ed750bd169 78 *
Anna Bridge 180:96ed750bd169 79 * @code
Anna Bridge 180:96ed750bd169 80 * class Foo {
Anna Bridge 180:96ed750bd169 81 * public:
AnnaBridge 168:9672193075cf 82 * Foo() : _resource(new Resource()) { }
Anna Bridge 180:96ed750bd169 83 * ~Foo() { delete _resource; }
AnnaBridge 168:9672193075cf 84 * private:
Anna Bridge 180:96ed750bd169 85 * // disallow copy operations
AnnaBridge 168:9672193075cf 86 * Foo(const Foo&);
AnnaBridge 168:9672193075cf 87 * Foo& operator=(const Foo&);
Anna Bridge 180:96ed750bd169 88 * // data members
AnnaBridge 168:9672193075cf 89 * Resource* _resource;
AnnaBridge 168:9672193075cf 90 * }
AnnaBridge 168:9672193075cf 91 * @endcode
Anna Bridge 180:96ed750bd169 92 *
Anna Bridge 180:96ed750bd169 93 * Another solution is to inherit privately from the NonCopyable class.
Anna Bridge 180:96ed750bd169 94 * It reduces the boiler plate needed to avoid copy operations but more
AnnaBridge 168:9672193075cf 95 * importantly it clarifies the programer intent and the object semantic.
AnnaBridge 168:9672193075cf 96 *
Anna Bridge 180:96ed750bd169 97 * class Foo : private NonCopyable<Foo> {
Anna Bridge 180:96ed750bd169 98 * public:
AnnaBridge 168:9672193075cf 99 * Foo() : _resource(new Resource()) { }
Anna Bridge 180:96ed750bd169 100 * ~Foo() { delete _resource; }
AnnaBridge 168:9672193075cf 101 * private:
AnnaBridge 168:9672193075cf 102 * Resource* _resource;
AnnaBridge 168:9672193075cf 103 * }
Anna Bridge 180:96ed750bd169 104 *
Anna Bridge 180:96ed750bd169 105 * @tparam T The type that should be made non copyable. It prevent cases where
Anna Bridge 180:96ed750bd169 106 * the empty base optimization cannot be applied and therefore ensure that the
Anna Bridge 180:96ed750bd169 107 * cost of this semantic sugar is null.
Anna Bridge 180:96ed750bd169 108 *
Anna Bridge 180:96ed750bd169 109 * As an example, the empty base optimization is prohibited if one of the empty
Anna Bridge 180:96ed750bd169 110 * base class is also a base type of the first non static data member:
Anna Bridge 180:96ed750bd169 111 *
Anna Bridge 180:96ed750bd169 112 * @code
AnnaBridge 168:9672193075cf 113 * struct A { };
Anna Bridge 180:96ed750bd169 114 * struct B : A {
AnnaBridge 168:9672193075cf 115 * int foo;
AnnaBridge 168:9672193075cf 116 * };
AnnaBridge 168:9672193075cf 117 * // thanks to empty base optimization, sizeof(B) == sizeof(int)
Anna Bridge 180:96ed750bd169 118 *
Anna Bridge 180:96ed750bd169 119 * struct C : A {
AnnaBridge 168:9672193075cf 120 * B b;
AnnaBridge 168:9672193075cf 121 * };
Anna Bridge 180:96ed750bd169 122 *
AnnaBridge 168:9672193075cf 123 * // empty base optimization cannot be applied here because A from C and A from
Anna Bridge 180:96ed750bd169 124 * // B shall have a different address. In that case, with the alignement
AnnaBridge 168:9672193075cf 125 * // sizeof(C) == 2* sizeof(int)
AnnaBridge 168:9672193075cf 126 * @endcode
Anna Bridge 180:96ed750bd169 127 *
Anna Bridge 180:96ed750bd169 128 * The solution to that problem is to templatize the empty class to makes it
Anna Bridge 180:96ed750bd169 129 * unique to the type it is applied to:
Anna Bridge 180:96ed750bd169 130 *
Anna Bridge 180:96ed750bd169 131 * @code
AnnaBridge 168:9672193075cf 132 * template<typename T>
AnnaBridge 168:9672193075cf 133 * struct A<T> { };
Anna Bridge 180:96ed750bd169 134 * struct B : A<B> {
AnnaBridge 168:9672193075cf 135 * int foo;
AnnaBridge 168:9672193075cf 136 * };
Anna Bridge 180:96ed750bd169 137 * struct C : A<C> {
AnnaBridge 168:9672193075cf 138 * B b;
AnnaBridge 168:9672193075cf 139 * };
Anna Bridge 180:96ed750bd169 140 *
Anna Bridge 180:96ed750bd169 141 * // empty base optimization can be applied B and C does not refer to the same
AnnaBridge 168:9672193075cf 142 * // kind of A. sizeof(C) == sizeof(B) == sizeof(int).
AnnaBridge 168:9672193075cf 143 * @endcode
Anna Bridge 180:96ed750bd169 144 *
Anna Bridge 180:96ed750bd169 145 * @note Compile time errors are disabled if the develop or the release profile
Anna Bridge 180:96ed750bd169 146 * is used. To override this behavior and force compile time errors in all profile
Anna Bridge 180:96ed750bd169 147 * set the configuration parameter "platform.force-non-copyable-error" to true.
AnnaBridge 168:9672193075cf 148 */
AnnaBridge 168:9672193075cf 149 template<typename T>
Anna Bridge 180:96ed750bd169 150 class NonCopyable {
AnnaBridge 168:9672193075cf 151 protected:
Anna Bridge 180:96ed750bd169 152 /**
AnnaBridge 168:9672193075cf 153 * Disalow construction of NonCopyable objects from outside of its hierarchy.
AnnaBridge 168:9672193075cf 154 */
AnnaBridge 168:9672193075cf 155 NonCopyable() { }
Anna Bridge 180:96ed750bd169 156 /**
AnnaBridge 168:9672193075cf 157 * Disalow destruction of NonCopyable objects from outside of its hierarchy.
AnnaBridge 168:9672193075cf 158 */
AnnaBridge 168:9672193075cf 159 ~NonCopyable() { }
AnnaBridge 168:9672193075cf 160
Anna Bridge 180:96ed750bd169 161 #if (!defined(MBED_DEBUG) && (MBED_CONF_PLATFORM_FORCE_NON_COPYABLE_ERROR == 0))
Anna Bridge 180:96ed750bd169 162 /**
Anna Bridge 180:96ed750bd169 163 * NonCopyable copy constructor.
Anna Bridge 180:96ed750bd169 164 *
Anna Bridge 180:96ed750bd169 165 * A compile time warning is issued when this function is used and a runtime
Anna Bridge 180:96ed750bd169 166 * warning is printed when the copy construction of the non copyable happens.
Anna Bridge 180:96ed750bd169 167 *
Anna Bridge 180:96ed750bd169 168 * If you see this warning, your code is probably doing something unspecified.
Anna Bridge 180:96ed750bd169 169 * Copy of non copyable resources can lead to resource leak and random error.
Anna Bridge 180:96ed750bd169 170 */
Anna Bridge 180:96ed750bd169 171 MBED_DEPRECATED("Invalid copy construction of a NonCopyable resource.")
Anna Bridge 180:96ed750bd169 172 NonCopyable(const NonCopyable&)
Anna Bridge 180:96ed750bd169 173 {
Anna Bridge 180:96ed750bd169 174 debug("Invalid copy construction of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
Anna Bridge 180:96ed750bd169 175 }
Anna Bridge 180:96ed750bd169 176
AnnaBridge 168:9672193075cf 177 /**
Anna Bridge 180:96ed750bd169 178 * NonCopyable copy assignment operator.
Anna Bridge 180:96ed750bd169 179 *
Anna Bridge 180:96ed750bd169 180 * A compile time warning is issued when this function is used and a runtime
Anna Bridge 180:96ed750bd169 181 * warning is printed when the copy construction of the non copyable happens.
Anna Bridge 180:96ed750bd169 182 *
Anna Bridge 180:96ed750bd169 183 * If you see this warning, your code is probably doing something unspecified.
Anna Bridge 180:96ed750bd169 184 * Copy of non copyable resources can lead to resource leak and random error.
Anna Bridge 180:96ed750bd169 185 */
Anna Bridge 180:96ed750bd169 186 MBED_DEPRECATED("Invalid copy assignment of a NonCopyable resource.")
Anna Bridge 180:96ed750bd169 187 NonCopyable& operator=(const NonCopyable&)
Anna Bridge 180:96ed750bd169 188 {
Anna Bridge 180:96ed750bd169 189 debug("Invalid copy assignment of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
Anna Bridge 180:96ed750bd169 190 return *this;
Anna Bridge 180:96ed750bd169 191 }
Anna Bridge 180:96ed750bd169 192
Anna Bridge 180:96ed750bd169 193 #else
Anna Bridge 180:96ed750bd169 194 private:
Anna Bridge 180:96ed750bd169 195 /**
Anna Bridge 180:96ed750bd169 196 * Declare copy constructor as private, any attempt to copy construct
AnnaBridge 168:9672193075cf 197 * a NonCopyable will fail at compile time.
AnnaBridge 168:9672193075cf 198 */
AnnaBridge 168:9672193075cf 199 NonCopyable(const NonCopyable&);
AnnaBridge 168:9672193075cf 200
AnnaBridge 168:9672193075cf 201 /**
Anna Bridge 180:96ed750bd169 202 * Declare copy assignement operator as private, any attempt to copy assign
AnnaBridge 168:9672193075cf 203 * a NonCopyable will fail at compile time.
AnnaBridge 168:9672193075cf 204 */
AnnaBridge 168:9672193075cf 205 NonCopyable& operator=(const NonCopyable&);
Anna Bridge 180:96ed750bd169 206 #endif
AnnaBridge 168:9672193075cf 207 };
AnnaBridge 168:9672193075cf 208
Anna Bridge 180:96ed750bd169 209 } // namespace mbed
AnnaBridge 168:9672193075cf 210
AnnaBridge 168:9672193075cf 211 #endif /* MBED_NONCOPYABLE_H_ */