mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

platform/NonCopyable.h@160:5571c4ff569f, 2018-01-17 (annotated)

Committer:
Anna Bridge
Date:
Wed Jan 17 16:13:02 2018 +0000
Revision:
160:5571c4ff569f
Parent:
146:22da6e220af6
Child:
165:d1b4690b3f8b
mbed library. Release version 158

Who changed what in which revision?

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