Pedro Correia / mbed-dev

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

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_ */