Diff: mbed-os/platform/NonCopyable.h

Revision:

0:9fca2b23d0ba

diff -r 000000000000 -r 9fca2b23d0ba mbed-os/platform/NonCopyable.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-os/platform/NonCopyable.h	Sat Feb 23 12:13:36 2019 +0000
@@ -0,0 +1,211 @@
+/* Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef MBED_NONCOPYABLE_H_
+#define MBED_NONCOPYABLE_H_
+
+#if (!defined(MBED_DEBUG) && (MBED_CONF_PLATFORM_FORCE_NON_COPYABLE_ERROR == 0))
+#include "mbed_toolchain.h"
+#include "mbed_debug.h"
+#endif
+
+namespace mbed {
+
+/**
+ * Inheriting from this class autogeneration of copy construction and copy
+ * assignement operations.
+ *
+ * Classes which are not value type should inherit privately from this class
+ * to avoid generation of invalid copy constructor or copy assignement operator
+ * which can lead to unoticeable programming errors.
+ *
+ * As an example consider the following signature:
+ *
+ * @code
+ * class Resource;
+ *
+ * class Foo {
+ * public:
+ *   Foo() : _resource(new Resource()) { }
+ *   ~Foo() { delete _resource; }
+ * private:
+ *   Resource* _resource;
+ * }
+ *
+ * Foo get_foo();
+ *
+ * Foo foo = get_foo();
+ * @endcode
+ *
+ * There is a bug in this function, it returns a temporary value which will be
+ * byte copied into foo then destroyed. Unfortunately, internaly the Foo class
+ * manage a pointer to a Resource object. This pointer will be released when the
+ * temporary is destroyed and foo will manage a pointer to an already released
+ * Resource.
+ *
+ * Two issues has to be fixed in the example above:
+ *   - Function signature has to be changed to reflect the fact that Foo
+ *     instances cannot be copied. In that case accessor should return a
+ *     reference to give access to objects already existing and managed.
+ *     Generator on the other hand should return a pointer to the created object.
+ *
+ * @code
+ * // return a reference to an already managed Foo instance
+ * Foo& get_foo();
+ * Foo& foo = get_foo();
+ *
+ * // create a new Foo instance
+ * Foo* make_foo();
+ * Foo* m = make_foo();
+ * @endcode
+ *
+ *   - Copy constructor and copy assignement operator has to be made private
+ *     in the Foo class. It prevents unwanted copy of Foo objects. This can be
+ *     done by declaring copy constructor and copy assignement in the private
+ *     section of the Foo class.
+ *
+ * @code
+ * class Foo {
+ * public:
+ *   Foo() : _resource(new Resource()) { }
+ *   ~Foo() { delete _resource; }
+ * private:
+ *   // disallow copy operations
+ *   Foo(const Foo&);
+ *   Foo& operator=(const Foo&);
+ *   // data members
+ *   Resource* _resource;
+ * }
+ * @endcode
+ *
+ * Another solution is to inherit privately from the NonCopyable class.
+ * It reduces the boiler plate needed to avoid copy operations but more
+ * importantly it clarifies the programer intent and the object semantic.
+ *
+ * class Foo : private NonCopyable<Foo> {
+ * public:
+ *   Foo() : _resource(new Resource()) { }
+ *   ~Foo() { delete _resource; }
+ * private:
+ *   Resource* _resource;
+ * }
+ *
+ * @tparam T The type that should be made non copyable. It prevent cases where
+ * the empty base optimization cannot be applied and therefore ensure that the
+ * cost of this semantic sugar is null.
+ *
+ * As an example, the empty base optimization is prohibited if one of the empty
+ * base class is also a base type of the first non static data member:
+ *
+ * @code
+ * struct A { };
+ * struct B : A {
+ *    int foo;
+ * };
+ * // thanks to empty base optimization, sizeof(B) == sizeof(int)
+ *
+ * struct C : A {
+ *   B b;
+ * };
+ *
+ * // empty base optimization cannot be applied here because A from C and A from
+ * // B shall have a different address. In that case, with the alignement
+ * // sizeof(C) == 2* sizeof(int)
+ * @endcode
+ *
+ * The solution to that problem is to templatize the empty class to makes it
+ * unique to the type it is applied to:
+ *
+ * @code
+ * template<typename T>
+ * struct A<T> { };
+ * struct B : A<B> {
+ *    int foo;
+ * };
+ * struct C : A<C> {
+ *   B b;
+ * };
+ *
+ * // empty base optimization can be applied B and C does not refer to the same
+ * // kind of A. sizeof(C) == sizeof(B) == sizeof(int).
+ * @endcode
+ *
+ * @note Compile time errors are disabled if the develop or the release profile
+ * is used. To override this behavior and force compile time errors in all profile
+ * set the configuration parameter "platform.force-non-copyable-error" to true.
+ */
+template<typename T>
+class NonCopyable {
+protected:
+    /**
+     * Disalow construction of NonCopyable objects from outside of its hierarchy.
+     */
+    NonCopyable() { }
+    /**
+     * Disalow destruction of NonCopyable objects from outside of its hierarchy.
+     */
+    ~NonCopyable() { }
+
+#if (!defined(MBED_DEBUG) && (MBED_CONF_PLATFORM_FORCE_NON_COPYABLE_ERROR == 0))
+    /**
+     * NonCopyable copy constructor.
+     *
+     * A compile time warning is issued when this function is used and a runtime
+     * warning is printed when the copy construction of the non copyable happens.
+     *
+     * If you see this warning, your code is probably doing something unspecified.
+     * Copy of non copyable resources can lead to resource leak and random error.
+     */
+    MBED_DEPRECATED("Invalid copy construction of a NonCopyable resource.")
+    NonCopyable(const NonCopyable&)
+    {
+        debug("Invalid copy construction of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
+    }
+
+    /**
+     * NonCopyable copy assignment operator.
+     *
+     * A compile time warning is issued when this function is used and a runtime
+     * warning is printed when the copy construction of the non copyable happens.
+     *
+     * If you see this warning, your code is probably doing something unspecified.
+     * Copy of non copyable resources can lead to resource leak and random error.
+     */
+    MBED_DEPRECATED("Invalid copy assignment of a NonCopyable resource.")
+    NonCopyable& operator=(const NonCopyable&)
+    {
+        debug("Invalid copy assignment of a NonCopyable resource: %s\r\n", MBED_PRETTY_FUNCTION);
+        return *this;
+    }
+
+#else
+private:
+    /**
+     * Declare copy constructor as private, any attempt to copy construct
+     * a NonCopyable will fail at compile time.
+     */
+    NonCopyable(const NonCopyable&);
+
+    /**
+     * Declare copy assignement operator as private, any attempt to copy assign
+     * a NonCopyable will fail at compile time.
+     */
+    NonCopyable& operator=(const NonCopyable&);
+#endif
+};
+
+} // namespace mbed
+
+#endif /* MBED_NONCOPYABLE_H_ */