utils-lists 4.0.0
µOS++ C++ intrusive lists utilities
Loading...
Searching...
No Matches
micro_os_plus::utils::static_double_list_links Class Reference

A class for the core of a statically allocated double linked list (pointers to neighbours). More...

#include <micro-os-plus/utils/lists.h>

+ Inheritance diagram for micro_os_plus::utils::static_double_list_links:

Public Types

using is_statically_allocated = std::true_type
 Type indicating that the links node is statically allocated.
 

Public Member Functions

constexpr static_double_list_links ()
 Construct a statically allocated list node (bss initialised).
 
constexpr ~static_double_list_links ()
 Destruct the node.
 
constexpr void initialize (void)
 Initialise the node links.
 
void initialize_once (void)
 Initialize the list only at first run.
 
void link_next (double_list_links_base *node)
 Link the new node as next.
 
void link_previous (double_list_links_base *node)
 Link the new node as previous.
 
bool linked (void) const
 Check if the node is linked to a double list.
 
constexpr double_list_links_basenext (void) const
 Get the link to the next node.
 
void nullify (void)
 Reset the two pointers to nullptr.
 
constexpr double_list_links_baseprevious (void) const
 Get the link to the previous node.
 
bool uninitialized (void) const
 Check if the node is uninitialised.
 
void unlink (void)
 Remove this node from the list.
 

Protected Attributes

double_list_links_basenext_
 Pointer to the next node.
 
double_list_links_baseprevious_
 Pointer to the previous node.
 

Detailed Description

A class for the core of a statically allocated double linked list (pointers to neighbours).

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 306 of file lists.h.

Member Typedef Documentation

◆ is_statically_allocated

Type indicating that the links node is statically allocated.

Definition at line 312 of file lists.h.

Constructor & Destructor Documentation

◆ static_double_list_links()

constexpr micro_os_plus::utils::static_double_list_links::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.

Warning
Code analysis may trigger:
  • Member 'previous_' was not initialized in constructor
  • Member 'next_' was not initialized in constructor

Definition at line 120 of file inlines.h.

◆ ~static_double_list_links()

constexpr micro_os_plus::utils::static_double_list_links::~static_double_list_links ( )
constexpr

Destruct the node.

Warning
GCC optimizes out the content (dead store elimination).
`did not help. The workaround is to usenullify()explicitly, or, even better, to clear the memory before invoking the placement new` constructor again.

Definition at line 140 of file inlines.h.

Member Function Documentation

◆ initialize()

constexpr void micro_os_plus::utils::double_list_links_base::initialize ( void )
constexprinherited

Initialise the node links.

Parameters
None.
Returns
Nothing.

Set both pointers to point to this node.

This is the definition of an unlinked node.

Note
After unlinking the node from a list, it must be returned to this state.

Definition at line 79 of file inlines.h.

◆ initialize_once()

void micro_os_plus::utils::double_list_links_base::initialize_once ( void )
inherited

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.

Note
This method must be manually called for statically allocated list before inserting elements, or performing any other operations.

Definition at line 73 of file lists.cpp.

◆ link_next()

void micro_os_plus::utils::double_list_links_base::link_next ( double_list_links_base * node)
inherited

Link the new node as next.

Parameters
None.
Returns
Nothing.

Insert the new node between the next pointer and the node pointed by it.

Used by lists to link new nodes to the list head.

Definition at line 89 of file lists.cpp.

◆ link_previous()

void micro_os_plus::utils::double_list_links_base::link_previous ( double_list_links_base * node)
inherited

Link the new node as previous.

Parameters
None.
Returns
Nothing.

Insert the new node between the previous pointer and the node pointed by it.

Used by lists to link new nodes to the list tail.

Definition at line 113 of file lists.cpp.

◆ linked()

bool micro_os_plus::utils::double_list_links_base::linked ( void ) const
inherited

Check if the node is linked to a double list.

Return values
trueThe node is linked with both pointers.
falseThe node is not linked.

To be linked, both pointers must point to different nodes than itself (double list requirement).

Definition at line 161 of file lists.cpp.

◆ next()

constexpr double_list_links_base * micro_os_plus::utils::double_list_links_base::next ( void ) const
constexprinherited

Get the link to the next node.

Return values
Pointerto the next node.

Definition at line 92 of file inlines.h.

◆ nullify()

void micro_os_plus::utils::static_double_list_links::nullify ( void )

Reset the two pointers to nullptr.

Parameters
None.
Returns
Nothing.
Warning
Not very safe, since the compiler may optimise out the code.

Definition at line 184 of file lists.cpp.

◆ previous()

constexpr double_list_links_base * micro_os_plus::utils::double_list_links_base::previous ( void ) const
constexprinherited

Get the link to the previous node.

Return values
Pointerto the previous node.

Definition at line 98 of file inlines.h.

◆ uninitialized()

bool micro_os_plus::utils::double_list_links_base::uninitialized ( void ) const
inherited

Check if the node is uninitialised.

Parameters
None.
Return values
trueThe links are not initialised.
falseThe 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.

Definition at line 46 of file lists.cpp.

◆ unlink()

void micro_os_plus::utils::double_list_links_base::unlink ( void )
inherited

Remove this node from the list.

Returns
Nothing.

Update both neighbours to point to each other, practically removing the node from the list.

The node is returned to the initial state (empty), with both pointers pointing to itself.

Definition at line 138 of file lists.cpp.

Member Data Documentation

◆ next_

double_list_links_base* micro_os_plus::utils::double_list_links_base::next_
protectedinherited

Pointer to the next node.

Definition at line 212 of file lists.h.

◆ previous_

double_list_links_base* micro_os_plus::utils::double_list_links_base::previous_
protectedinherited

Pointer to the previous node.

Definition at line 207 of file lists.h.


The documentation for this class was generated from the following files: