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@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

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