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@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
170:e95d10626187
Child:
172:65be27845400
mbed library. Release version 164

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 171:3a7713b1edbc 26 /** \addtogroup platform */
AnnaBridge 171:3a7713b1edbc 27 /** @{*/
AnnaBridge 146:22da6e220af6 28 /**
AnnaBridge 171:3a7713b1edbc 29 * \defgroup platform_NonCopyable NonCopyable class
AnnaBridge 171:3a7713b1edbc 30 * @{
AnnaBridge 171:3a7713b1edbc 31 */
AnnaBridge 171:3a7713b1edbc 32
AnnaBridge 171:3a7713b1edbc 33 /**
AnnaBridge 171:3a7713b1edbc 34 * Prevents generation of copy constructor and copy assignment operator in
AnnaBridge 171:3a7713b1edbc 35 * derived classes.
AnnaBridge 171:3a7713b1edbc 36 *
AnnaBridge 171:3a7713b1edbc 37 * @par Usage
AnnaBridge 171:3a7713b1edbc 38 *
AnnaBridge 171:3a7713b1edbc 39 * To prevent generation of copy constructor and copy assignment operator,
AnnaBridge 171:3a7713b1edbc 40 * inherit privately from the NonCopyable class.
AnnaBridge 171:3a7713b1edbc 41 *
AnnaBridge 171:3a7713b1edbc 42 * @code
AnnaBridge 171:3a7713b1edbc 43 * class Resource : NonCopyable<Resource> { };
AnnaBridge 171:3a7713b1edbc 44 *
AnnaBridge 171:3a7713b1edbc 45 * Resource r;
AnnaBridge 171:3a7713b1edbc 46 * // generates compile time error:
AnnaBridge 171:3a7713b1edbc 47 * Resource r2 = r;
AnnaBridge 171:3a7713b1edbc 48 * @endcode
AnnaBridge 171:3a7713b1edbc 49 *
AnnaBridge 171:3a7713b1edbc 50 * @par Background information
AnnaBridge 171:3a7713b1edbc 51 *
AnnaBridge 171:3a7713b1edbc 52 * Instances of polymorphic classes are not meant to be copied. The
AnnaBridge 171:3a7713b1edbc 53 * C++ standards generate a default copy constructor and copy assignment
AnnaBridge 171:3a7713b1edbc 54 * function if these functions have not been defined in the class.
AnnaBridge 171:3a7713b1edbc 55 *
AnnaBridge 171:3a7713b1edbc 56 * Consider the following example:
AnnaBridge 171:3a7713b1edbc 57 *
AnnaBridge 146:22da6e220af6 58 * @code
AnnaBridge 171:3a7713b1edbc 59 * // base class representing a connection
AnnaBridge 171:3a7713b1edbc 60 * struct Connection {
AnnaBridge 171:3a7713b1edbc 61 * Connection();
AnnaBridge 171:3a7713b1edbc 62 * virtual ~Connection();
AnnaBridge 171:3a7713b1edbc 63 * virtual void open() = 0;
AnnaBridge 171:3a7713b1edbc 64 * }
AnnaBridge 171:3a7713b1edbc 65 *
AnnaBridge 171:3a7713b1edbc 66 * class SerialConnection : public Connection {
Anna Bridge 160:5571c4ff569f 67 * public:
AnnaBridge 171:3a7713b1edbc 68 * SerialConnection(Serial*);
AnnaBridge 171:3a7713b1edbc 69 *
AnnaBridge 146:22da6e220af6 70 * private:
AnnaBridge 171:3a7713b1edbc 71 * Serial* _serial;
AnnaBridge 171:3a7713b1edbc 72 * };
AnnaBridge 171:3a7713b1edbc 73 *
AnnaBridge 171:3a7713b1edbc 74 * Connection& get_connection() {
AnnaBridge 171:3a7713b1edbc 75 * static SerialConnection serial_connection;
AnnaBridge 171:3a7713b1edbc 76 * return serial_connection;
AnnaBridge 146:22da6e220af6 77 * }
Anna Bridge 160:5571c4ff569f 78 *
AnnaBridge 171:3a7713b1edbc 79 * Connection connection = get_connection();
Anna Bridge 160:5571c4ff569f 80 * @endcode
AnnaBridge 171:3a7713b1edbc 81 *
AnnaBridge 171:3a7713b1edbc 82 * There is a subtle bug in this code, the function get_connection returns a
AnnaBridge 171:3a7713b1edbc 83 * reference to a Connection which is captured by value instead of reference.
AnnaBridge 171:3a7713b1edbc 84 *
AnnaBridge 171:3a7713b1edbc 85 * When `get_connection` returns a reference to serial_connection it is copied into
AnnaBridge 171:3a7713b1edbc 86 * the local variable connection. The vtable and others members defined in Connection
AnnaBridge 171:3a7713b1edbc 87 * are copied, but members defined in SerialConnection are left apart. This can cause
AnnaBridge 171:3a7713b1edbc 88 * severe crashes or bugs if the virtual functions captured use members not present
AnnaBridge 171:3a7713b1edbc 89 * in the base declaration.
AnnaBridge 171:3a7713b1edbc 90 *
AnnaBridge 171:3a7713b1edbc 91 * To solve that problem, the copy constructor and assignment operator have to
AnnaBridge 171:3a7713b1edbc 92 * be declared (but don't need to be defined) in the private section of the
AnnaBridge 171:3a7713b1edbc 93 * Connection class:
AnnaBridge 171:3a7713b1edbc 94 *
Anna Bridge 160:5571c4ff569f 95 * @code
AnnaBridge 171:3a7713b1edbc 96 * struct Connection {
AnnaBridge 146:22da6e220af6 97 * private:
AnnaBridge 171:3a7713b1edbc 98 * Connection(const Connection&);
AnnaBridge 171:3a7713b1edbc 99 * Connection& operator=(const Connection&);
AnnaBridge 146:22da6e220af6 100 * }
AnnaBridge 146:22da6e220af6 101 * @endcode
AnnaBridge 171:3a7713b1edbc 102 *
AnnaBridge 171:3a7713b1edbc 103 * Although manually declaring private copy constructor and assignment functions
AnnaBridge 171:3a7713b1edbc 104 * works, it is not ideal. These declarations are usually easy to forget,
AnnaBridge 171:3a7713b1edbc 105 * not immediately visible, and may be obscure to uninformed programmers.
AnnaBridge 171:3a7713b1edbc 106 *
AnnaBridge 171:3a7713b1edbc 107 * Using the NonCopyable class reduces the boilerplate required and expresses
AnnaBridge 171:3a7713b1edbc 108 * the intent because class inheritance appears right after the class name
AnnaBridge 171:3a7713b1edbc 109 * declaration.
AnnaBridge 171:3a7713b1edbc 110 *
AnnaBridge 171:3a7713b1edbc 111 * @code
AnnaBridge 171:3a7713b1edbc 112 * struct Connection : private NonCopyable<Connection> {
AnnaBridge 171:3a7713b1edbc 113 * // regular declarations
AnnaBridge 146:22da6e220af6 114 * }
AnnaBridge 171:3a7713b1edbc 115 * @endcode
AnnaBridge 171:3a7713b1edbc 116 *
AnnaBridge 171:3a7713b1edbc 117 *
AnnaBridge 171:3a7713b1edbc 118 * @par Implementation details
AnnaBridge 171:3a7713b1edbc 119 *
AnnaBridge 171:3a7713b1edbc 120 * Using a template type prevents cases where the empty base optimization cannot
AnnaBridge 171:3a7713b1edbc 121 * be applied and therefore ensures that the cost of the NonCopyable semantic
AnnaBridge 171:3a7713b1edbc 122 * sugar is null.
AnnaBridge 171:3a7713b1edbc 123 *
Anna Bridge 160:5571c4ff569f 124 * As an example, the empty base optimization is prohibited if one of the empty
AnnaBridge 171:3a7713b1edbc 125 * base classes is also a base type of the first nonstatic data member:
Anna Bridge 160:5571c4ff569f 126 *
Anna Bridge 160:5571c4ff569f 127 * @code
AnnaBridge 146:22da6e220af6 128 * struct A { };
Anna Bridge 160:5571c4ff569f 129 * struct B : A {
AnnaBridge 146:22da6e220af6 130 * int foo;
AnnaBridge 146:22da6e220af6 131 * };
AnnaBridge 146:22da6e220af6 132 * // thanks to empty base optimization, sizeof(B) == sizeof(int)
Anna Bridge 160:5571c4ff569f 133 *
Anna Bridge 160:5571c4ff569f 134 * struct C : A {
AnnaBridge 146:22da6e220af6 135 * B b;
AnnaBridge 146:22da6e220af6 136 * };
Anna Bridge 160:5571c4ff569f 137 *
AnnaBridge 146:22da6e220af6 138 * // empty base optimization cannot be applied here because A from C and A from
AnnaBridge 171:3a7713b1edbc 139 * // B have a different address. In that case, with the alignment
AnnaBridge 146:22da6e220af6 140 * // sizeof(C) == 2* sizeof(int)
AnnaBridge 146:22da6e220af6 141 * @endcode
Anna Bridge 160:5571c4ff569f 142 *
AnnaBridge 171:3a7713b1edbc 143 * The solution to that problem is to templatize the empty class to make it
Anna Bridge 160:5571c4ff569f 144 * unique to the type it is applied to:
Anna Bridge 160:5571c4ff569f 145 *
Anna Bridge 160:5571c4ff569f 146 * @code
AnnaBridge 146:22da6e220af6 147 * template<typename T>
AnnaBridge 146:22da6e220af6 148 * struct A<T> { };
Anna Bridge 160:5571c4ff569f 149 * struct B : A<B> {
AnnaBridge 146:22da6e220af6 150 * int foo;
AnnaBridge 146:22da6e220af6 151 * };
Anna Bridge 160:5571c4ff569f 152 * struct C : A<C> {
AnnaBridge 146:22da6e220af6 153 * B b;
AnnaBridge 146:22da6e220af6 154 * };
Anna Bridge 160:5571c4ff569f 155 *
Anna Bridge 160:5571c4ff569f 156 * // empty base optimization can be applied B and C does not refer to the same
AnnaBridge 146:22da6e220af6 157 * // kind of A. sizeof(C) == sizeof(B) == sizeof(int).
AnnaBridge 146:22da6e220af6 158 * @endcode
Anna Bridge 160:5571c4ff569f 159 *
AnnaBridge 171:3a7713b1edbc 160 * @tparam T The type that should be made noncopyable.
AnnaBridge 171:3a7713b1edbc 161 *
AnnaBridge 171:3a7713b1edbc 162 * @note Compile time errors are disabled if you use the develop or release profile.
AnnaBridge 171:3a7713b1edbc 163 * To override this behavior and force compile time errors in all profiles,
Anna Bridge 160:5571c4ff569f 164 * set the configuration parameter "platform.force-non-copyable-error" to true.
AnnaBridge 146:22da6e220af6 165 */
AnnaBridge 146:22da6e220af6 166 template<typename T>
Anna Bridge 160:5571c4ff569f 167 class NonCopyable {
AnnaBridge 171:3a7713b1edbc 168 #ifndef DOXYGEN_ONLY
AnnaBridge 146:22da6e220af6 169 protected:
Anna Bridge 160:5571c4ff569f 170 /**
AnnaBridge 165:d1b4690b3f8b 171 * Disallow construction of NonCopyable objects from outside of its hierarchy.
AnnaBridge 146:22da6e220af6 172 */
AnnaBridge 146:22da6e220af6 173 NonCopyable() { }
Anna Bridge 160:5571c4ff569f 174 /**
AnnaBridge 165:d1b4690b3f8b 175 * Disallow destruction of NonCopyable objects from outside of its hierarchy.
AnnaBridge 146:22da6e220af6 176 */
AnnaBridge 146:22da6e220af6 177 ~NonCopyable() { }
AnnaBridge 146:22da6e220af6 178
Anna Bridge 160:5571c4ff569f 179 #if (!defined(MBED_DEBUG) && (MBED_CONF_PLATFORM_FORCE_NON_COPYABLE_ERROR == 0))
Anna Bridge 160:5571c4ff569f 180 /**
Anna Bridge 160:5571c4ff569f 181 * NonCopyable copy constructor.
Anna Bridge 160:5571c4ff569f 182 *
AnnaBridge 171:3a7713b1edbc 183 * A compile time warning is issued when this function is used, and a runtime
AnnaBridge 171:3a7713b1edbc 184 * warning is printed when the copy construction of the noncopyable happens.
Anna Bridge 160:5571c4ff569f 185 *
Anna Bridge 160:5571c4ff569f 186 * If you see this warning, your code is probably doing something unspecified.
AnnaBridge 171:3a7713b1edbc 187 * Copying of noncopyable resources can lead to resource leak and random error.
Anna Bridge 160:5571c4ff569f 188 */
Anna Bridge 160:5571c4ff569f 189 MBED_DEPRECATED("Invalid copy construction of a NonCopyable resource.")
AnnaBridge 170:e95d10626187 190 NonCopyable(const NonCopyable &)
Anna Bridge 160:5571c4ff569f 191 {
Anna Bridge 160:5571c4ff569f 192 debug("Invalid copy construction of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
Anna Bridge 160:5571c4ff569f 193 }
Anna Bridge 160:5571c4ff569f 194
AnnaBridge 146:22da6e220af6 195 /**
Anna Bridge 160:5571c4ff569f 196 * NonCopyable copy assignment operator.
Anna Bridge 160:5571c4ff569f 197 *
AnnaBridge 171:3a7713b1edbc 198 * A compile time warning is issued when this function is used, and a runtime
AnnaBridge 171:3a7713b1edbc 199 * warning is printed when the copy construction of the noncopyable happens.
Anna Bridge 160:5571c4ff569f 200 *
Anna Bridge 160:5571c4ff569f 201 * If you see this warning, your code is probably doing something unspecified.
AnnaBridge 171:3a7713b1edbc 202 * Copying of noncopyable resources can lead to resource leak and random error.
Anna Bridge 160:5571c4ff569f 203 */
Anna Bridge 160:5571c4ff569f 204 MBED_DEPRECATED("Invalid copy assignment of a NonCopyable resource.")
AnnaBridge 170:e95d10626187 205 NonCopyable &operator=(const NonCopyable &)
Anna Bridge 160:5571c4ff569f 206 {
Anna Bridge 160:5571c4ff569f 207 debug("Invalid copy assignment of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
Anna Bridge 160:5571c4ff569f 208 return *this;
Anna Bridge 160:5571c4ff569f 209 }
Anna Bridge 160:5571c4ff569f 210
Anna Bridge 160:5571c4ff569f 211 #else
Anna Bridge 160:5571c4ff569f 212 private:
Anna Bridge 160:5571c4ff569f 213 /**
AnnaBridge 171:3a7713b1edbc 214 * Declare copy constructor as private. Any attempt to copy construct
AnnaBridge 146:22da6e220af6 215 * a NonCopyable will fail at compile time.
AnnaBridge 146:22da6e220af6 216 */
AnnaBridge 170:e95d10626187 217 NonCopyable(const NonCopyable &);
AnnaBridge 146:22da6e220af6 218
AnnaBridge 146:22da6e220af6 219 /**
AnnaBridge 171:3a7713b1edbc 220 * Declare copy assignment operator as private. Any attempt to copy assign
AnnaBridge 146:22da6e220af6 221 * a NonCopyable will fail at compile time.
AnnaBridge 146:22da6e220af6 222 */
AnnaBridge 170:e95d10626187 223 NonCopyable &operator=(const NonCopyable &);
Anna Bridge 160:5571c4ff569f 224 #endif
AnnaBridge 171:3a7713b1edbc 225 #endif
AnnaBridge 146:22da6e220af6 226 };
AnnaBridge 146:22da6e220af6 227
AnnaBridge 171:3a7713b1edbc 228 /**@}*/
AnnaBridge 171:3a7713b1edbc 229
AnnaBridge 171:3a7713b1edbc 230 /**@}*/
AnnaBridge 171:3a7713b1edbc 231
Anna Bridge 160:5571c4ff569f 232 } // namespace mbed
AnnaBridge 146:22da6e220af6 233
AnnaBridge 146:22da6e220af6 234 #endif /* MBED_NONCOPYABLE_H_ */