When a Doxygen group has been defined (created), all its needed to add
documentation to that group is `\addtogroup`. Since all the information
about the group is preserved, it is not necessary to mention the group
hierarchy again with `\ingroup`. This PR removes unnecessary Doxygen lines
across the `drivers`, `events`, `platform` and `rtos` directories.
It also ensures that new groups are created with `\defgroup` once and
referenced with `\addtogroup` whenever documentation needs to be added to
an existing group.
* Change Doxygen groups structure, splitting first by Public/Internal
This commit also does the following:
* groups the documentation of related API
* moves `events/internal/equeue.h` to `events/equeue.h`
* merges `events/source/README.md` to `events/README.md`
Also includes:
* rename `mbed_sleep_manager.c` to `mbed_power_mgmt.c` to match its
header file
* create Doxygen groups for public and internal APIs
* use relative path to include header files where inconsistent
* update references to internal APIs throughout libraries
* update the copyright year for all modified files
* Adjust definition to make the default constructor `constexpr`.
This permits use in classes that want lazy initialization and their
own `constexpr` constructor, such as `mstd::mutex`.
* Add `get_no_init()` method to allow an explicit optimisation for
paths that know they won be the first call (such as
`mstd::mutex::unlock`).
* Add `destroy()` method to permit destruction of the contained object.
(`SingletonPtr`'s destructor does not call its destructor - a cheat
to omit destructors of static objects). Needed if using in a class
that needs proper destruction.
Minor tweaks to fix ARM C 5 compatibility.
Pushing "ns_list.h" include to first makes sure "ns_types.h" is included
first, meaning it gets to define `__STDC_LIMIT_MACROS` before the first
include of <stdint.h>, which ensures that UINT8_MAX etc are defined.
Reimplement atomic code in inline assembly. This can improve
optimisation, and avoids potential architectural problems with using
LDREX/STREX intrinsics.
API further extended:
* Bitwise operations (fetch_and/fetch_or/fetch_xor)
* fetch_add and fetch_sub (like incr/decr, but returning old value -
aligning with C++11)
* compare_exchange_weak
* Explicit memory order specification
* Basic freestanding template overloads for C++
This gives our existing C implementation essentially all the functionality
needed by C++11.
An actual Atomic<T> template based upon these C functions could follow.
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.
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).
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.
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*.
stop using scope for \addtogroup. It was placing class methods into the
group documentation instead of the class documentation. The new style is
to explicitly tag the class as @ingroup. This new method will allow the
class to be linked in the group page, and the class page will contain
the detailed documentation of the class methods.
Hugues Kamba
Kevin Bracey
Martin Kojtal
deepikabhavnani
Russ Butler
Senthil Ramakrishnan
Bartek Szatkowski
Sam Grove
Jimmy Brisson
Christopher Haster