ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
mbed-os/platform/SingletonPtr.h

147 lines
3.5 KiB
C
Raw Normal View History

Add tags to our code
2016-10-04 20:02:44 +00:00
/** \addtogroup platform */
/** @{*/
Doxygen comment updates and fixes
2017-10-24 15:05:45 +00:00
/**
* \defgroup platform_SingletonPtr SingletonPtr class
* @{
*/
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
/* mbed Microcontroller Library
* Copyright (c) 2006-2013 ARM Limited
platform: add spdx license
2018-11-09 11:31:20 +00:00
* SPDX-License-Identifier: Apache-2.0
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
*
* 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 SINGLETONPTR_H
#define SINGLETONPTR_H
Resolve build issue for unittest Error Resolved here is: SingletonPtr.h:93:13: error: ‘NULL’ was not declared in this scope
2018-11-26 15:53:19 +00:00
#include <stdlib.h>
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#include <stdint.h>
#include <new>
For drivers, events, hal, platform, rtos and mbed.h add one level of path to make sure specific and unique includes files are found.
2016-10-01 07:11:36 +00:00
#include "platform/mbed_assert.h"
Make SingletonPtr safe using atomics SingletonPtr's implementation wasn't totally safe - see "C++ and the Perils of Double-Checked Locking"by Meyers and Alexandrescu. No problems observed in practice, but it was potentially susceptible to compiler optimisation (or maybe even SMP issues). Now that we have atomic loads and stores, the function can be made safe, avoiding any potential races for threads that don't take the lock: ensure that the unlocked load is atomic, and that the pointer store is atomic. See https://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11/ for more discussion.
2019-01-29 09:14:02 +00:00
#include "platform/mbed_critical.h"
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#ifdef MBED_CONF_RTOS_PRESENT
Update codebase for CMSIS5/RTX5 Update all of mbed-os to use RTX5.
2017-05-15 14:55:45 +00:00
#include "cmsis_os2.h"
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#endif
#ifdef MBED_CONF_RTOS_PRESENT
Update codebase for CMSIS5/RTX5 Update all of mbed-os to use RTX5.
2017-05-15 14:55:45 +00:00
extern osMutexId_t singleton_mutex_id;
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#endif
/** Lock the singleton mutex
*
* This function is typically used to provide
* exclusive access when initializing a
* global object.
*/
inline static void singleton_lock(void)
{
#ifdef MBED_CONF_RTOS_PRESENT
Allow early use of singleton lock Allow singleton_lock and singleton_unlock to be called before the RTOS has been started by checking for a valid mutex before locking and unlocking it.
2018-08-13 15:34:08 +00:00
if (!singleton_mutex_id) {
// RTOS has not booted yet so no mutex is needed
return;
}
Update codebase for CMSIS5/RTX5 Update all of mbed-os to use RTX5.
2017-05-15 14:55:45 +00:00
osMutexAcquire(singleton_mutex_id, osWaitForever);
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#endif
}
/** Unlock the singleton mutex
*
* This function is typically used to provide
* exclusive access when initializing a
* global object.
*/
inline static void singleton_unlock(void)
{
#ifdef MBED_CONF_RTOS_PRESENT
Allow early use of singleton lock Allow singleton_lock and singleton_unlock to be called before the RTOS has been started by checking for a valid mutex before locking and unlocking it.
2018-08-13 15:34:08 +00:00
if (!singleton_mutex_id) {
// RTOS has not booted yet so no mutex is needed
return;
}
platform: astyle update
2018-06-27 14:09:15 +00:00
osMutexRelease(singleton_mutex_id);
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
#endif
}
/** Utility class for creating an using a singleton
*
[platform] Update doxygen errors from @Note to @note
2017-04-25 19:37:08 +00:00
* @note Synchronization level: Thread safe
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
*
[platform] Update doxygen errors from @Note to @note
2017-04-25 19:37:08 +00:00
* @note: This class must only be used in a static context -
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
* this class must never be allocated or created on the
* stack.
*
[platform] Update doxygen errors from @Note to @note
2017-04-25 19:37:08 +00:00
* @note: This class is lazily initialized on first use.
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
* This class is a POD type so if it is not used it will
* be garbage collected.
*/
template <class T>
struct SingletonPtr {
/** Get a pointer to the underlying singleton
*
* @returns
* A pointer to the singleton
*/
Make SingletonPtr methods const Make get() and operators * and -> of SingletonPtr const - they are logically const and thread-safe, despite the construction on first call. This construction is "invisible" to the caller of those methods.
2018-09-10 08:00:08 +00:00
T *get() const
platform: astyle update
2018-06-27 14:09:15 +00:00
{
Make SingletonPtr safe using atomics SingletonPtr's implementation wasn't totally safe - see "C++ and the Perils of Double-Checked Locking"by Meyers and Alexandrescu. No problems observed in practice, but it was potentially susceptible to compiler optimisation (or maybe even SMP issues). Now that we have atomic loads and stores, the function can be made safe, avoiding any potential races for threads that don't take the lock: ensure that the unlocked load is atomic, and that the pointer store is atomic. See https://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11/ for more discussion.
2019-01-29 09:14:02 +00:00
T *p = static_cast<T *>(core_util_atomic_load_ptr(&_ptr));
if (p == NULL) {
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
singleton_lock();
Make SingletonPtr safe using atomics SingletonPtr's implementation wasn't totally safe - see "C++ and the Perils of Double-Checked Locking"by Meyers and Alexandrescu. No problems observed in practice, but it was potentially susceptible to compiler optimisation (or maybe even SMP issues). Now that we have atomic loads and stores, the function can be made safe, avoiding any potential races for threads that don't take the lock: ensure that the unlocked load is atomic, and that the pointer store is atomic. See https://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11/ for more discussion.
2019-01-29 09:14:02 +00:00
p = static_cast<T *>(_ptr);
if (p == NULL) {
p = new (_data) T();
core_util_atomic_store_ptr(&_ptr, p);
Fix SingletonPtr problems Check to see if ptr is NULL after acquiring the singleton lock to prevent initialization race conditions. Also explicitly call the constructor for type T.
2016-08-19 23:40:06 +00:00
}
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
singleton_unlock();
}
// _ptr was not zero initialized or was
// corrupted if this assert is hit
Make SingletonPtr safe using atomics SingletonPtr's implementation wasn't totally safe - see "C++ and the Perils of Double-Checked Locking"by Meyers and Alexandrescu. No problems observed in practice, but it was potentially susceptible to compiler optimisation (or maybe even SMP issues). Now that we have atomic loads and stores, the function can be made safe, avoiding any potential races for threads that don't take the lock: ensure that the unlocked load is atomic, and that the pointer store is atomic. See https://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11/ for more discussion.
2019-01-29 09:14:02 +00:00
MBED_ASSERT(p == reinterpret_cast<T *>(&_data));
return p;
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
}
/** Get a pointer to the underlying singleton
*
* @returns
* A pointer to the singleton
*/
Make SingletonPtr methods const Make get() and operators * and -> of SingletonPtr const - they are logically const and thread-safe, despite the construction on first call. This construction is "invisible" to the caller of those methods.
2018-09-10 08:00:08 +00:00
T *operator->() const
platform: astyle update
2018-06-27 14:09:15 +00:00
{
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
return get();
}
Add * operator to SingletonPtr Sometimes you want don't want to directly call a method on your SingletonPtr-wrapped object, but you want to pass it to something else. For example SingletonPtr<PlatformMutex> mutex; mutex->lock(); is fine, but what about SingletonPtr<PlatformMutex> mutex; ScopedLock<PlatformMutex> lock(*mutex.get()); Add an overload for operator* to make this more elegant: SingletonPtr<PlatformMutex> mutex; ScopedLock<PlatformMutex> lock(*mutex); This addition is consistent with standard C++ classes such as `unique_ptr` and `shared_ptr`, which likewise have get, operator-> and operator*.
2018-08-29 13:36:55 +00:00
/** Get a reference to the underlying singleton
*
* @returns
* A reference to the singleton
*/
Make SingletonPtr methods const Make get() and operators * and -> of SingletonPtr const - they are logically const and thread-safe, despite the construction on first call. This construction is "invisible" to the caller of those methods.
2018-09-10 08:00:08 +00:00
T &operator*() const
Add * operator to SingletonPtr Sometimes you want don't want to directly call a method on your SingletonPtr-wrapped object, but you want to pass it to something else. For example SingletonPtr<PlatformMutex> mutex; mutex->lock(); is fine, but what about SingletonPtr<PlatformMutex> mutex; ScopedLock<PlatformMutex> lock(*mutex.get()); Add an overload for operator* to make this more elegant: SingletonPtr<PlatformMutex> mutex; ScopedLock<PlatformMutex> lock(*mutex); This addition is consistent with standard C++ classes such as `unique_ptr` and `shared_ptr`, which likewise have get, operator-> and operator*.
2018-08-29 13:36:55 +00:00
{
return *get();
}
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
// This is zero initialized when in global scope
Make SingletonPtr safe using atomics SingletonPtr's implementation wasn't totally safe - see "C++ and the Perils of Double-Checked Locking"by Meyers and Alexandrescu. No problems observed in practice, but it was potentially susceptible to compiler optimisation (or maybe even SMP issues). Now that we have atomic loads and stores, the function can be made safe, avoiding any potential races for threads that don't take the lock: ensure that the unlocked load is atomic, and that the pointer store is atomic. See https://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11/ for more discussion.
2019-01-29 09:14:02 +00:00
mutable void *_ptr;
Align SingletonPtr data to 8 bytes, or use C++11 Be more cautious about alignment - align the data within a SingletonPtr to 8 bytes rather than 4. This could increase padding overhead by up to 8 bytes, sadly, but we may need this alignment for correct operation. Conditional check added for C++11 - if in use we can get correct minimal alignment by using alignas(T).
2018-09-10 08:10:41 +00:00
#if __cplusplus >= 201103L
// Align data appropriately
alignas(T) mutable char _data[sizeof(T)];
#else
// Force data to be 8 byte aligned
mutable uint64_t _data[(sizeof(T) + sizeof(uint64_t) - 1) / sizeof(uint64_t)];
#endif
Create singleton class and update code to use it Create the wrapper class SingletonPtr. This provides a safe way to declare and use singletons. This class allows both the lazy initialization of a singleton, and allows the singleton to be garbage collected by the linker if it is never referenced. This patch also updates the HAL to use SingletonPtr when declaring singleton mutexes.
2016-06-27 23:55:07 +00:00
};
#endif
Doxygen comment updates and fixes
2017-10-24 15:05:45 +00:00
/**@}*/
Add tags to our code
2016-10-04 20:02:44 +00:00
Doxygen comment updates and fixes
2017-10-24 15:05:45 +00:00
/**@}*/