The static_double_list_links Class Reference
A class for the core of a statically allocated doubly linked list (pointers to neighbours). More...
Fully Qualified Name
micro_os_plus::utils::static_double_list_links
Included Headers
#include <micro-os-plus/utils/lists.h>Base class
class | |
A base class for a doubly linked list. More... | |
Member Typedefs
using | is_statically_allocated = std::true_type |
Type indicating that the links node is statically allocated. More... | |
Member Functions
constexpr | |
Construct a statically allocated list node (bss initialised). More... | |
constexpr | |
Destruct the node. More... | |
void | initialize (void) |
Initialise the node links. More... | |
void | initialize_once (void) |
Initialize the list only at first run. More... | |
void | link_next (double_list_links_base *node) |
Link the new node as next. More... | |
void | link_previous (double_list_links_base *node) |
Link the new node as previous. More... | |
bool | linked (void) const |
Check if the node is linked to a double list. More... | |
next (void) const | |
Get the link to the next node. More... | |
void | nullify (void) |
Reset the two pointers to | |
previous (void) const | |
Get the link to the previous node. More... | |
bool | uninitialized (void) const |
Check if the node is uninitialised. More... | |
void | unlink (void) |
Remove this node from the list. More... | |
Protected Member Attributes
Pointer to the next node. More... | |
Pointer to the previous node. More... | |
Description
The pair of uninitialised pointers to the next and previous list elements and the methods to access the pointers are inherited from the base class.
It is expected that instances of this class to be statically allocated in the bss section and cleared (set to zero) during startup.
These peculiar types of lists are used by registrars, to automate the self-registration of other statically allocated objects, like drivers, threads, etc.
Since the order of static constructors is not defined, it is perfectly and legally possible that the constructor of the registrar will be invoked after the constructors of the objects that need to register into the list, thus the registrar must be guaranteed to be initialised before running any static constructors.
The solution is to design the object in such a way as to benefit from the standard bss initialisation, in other words take nullptr as starting values.
In practical terms, the list initialisation cannot be done in the constructor, but must be manually done before any method that adds elements to the list is called.
Definition at line 323 of file lists.h.
Constructors
static_double_list_links()
| constexpr |
Construct a statically allocated list node (bss initialised).
As the name implies, it is assumed that the instance of the object is allocated statically and the entire content was set to zero during startup (via BSS init).
This is equivalent to setting the pointers to nullptr.
Code analysis may trigger:
- Member
previous_was not initialized in constructor - Member
next_was not initialized in constructor
Destructor
~static_double_list_links()
| constexpr |
Destruct the node.
The code to clear the pointers is now commented out, since recent GCC optimizes it out (dead store elimination). Depending on the version, there might be some attributes to allow this, but they are not safe, for example
__attribute__((optimize("no-lifetime-dse,no-dse,no-inline"))) did not help. The workaround is to use nullify() explicitly, or, even better, to clear the memory before invoking the placement new constructor again.
Member Functions
initialize()
| constexpr |
initialize_once()
|
Initialize the list only at first run.
- Parameters
None.
- Returns
Nothing.
If the statically allocated list is still in the initial uninitialised state (with both pointers nullptr), initialise the list to the empty state, with both pointers pointing to itself.
For non-statically initialised lists, this method is ineffective, since the node is always initialised at construct time.
This method must be manually called for statically allocated list before inserting elements, or performing any other operations.
link_next()
|
link_previous()
|
linked()
|
next()
| constexpr |
nullify()
|
previous()
| constexpr |
uninitialized()
|
Check if the node is uninitialised.
- Parameters
None.
- Return Values
true The links are not initialised. false The links are initialised.
An uninitialized node is a node with the pointers set to nullptr.
Only statically allocated nodes in the initial state are uninitialized. Regular nodes are always initialised.
unlink()
|
Protected Member Attributes
next_
| protected |
previous_
Generated via docusaurus-plugin-doxygen by Doxygen 1.13.2