The double_list_links_base
Class Reference
A base class for a doubly linked list node. More...
Declaration
class micro_os_plus::utils::double_list_links_base;
Included Headers
#include <micro-os-plus/utils/lists.h>
Derived Classes
class | double_list_links |
A class for the core of a doubly linked list (pointers to neighbours). More... | |
class | static_double_list_links |
A class for the core of a statically allocated doubly linked list (pointers to neighbours). More... | |
Protected Member Attributes Index
double_list_links_base * | next_ |
Pointer to the next node. More... | |
double_list_links_base * | previous_ |
Pointer to the previous node. More... | |
Public Constructors Index
constexpr | double_list_links_base () |
Construct an uninitialised list node. More... | |
double_list_links_base (const double_list_links_base &)=delete | |
Deleted copy constructor. More... | |
double_list_links_base (double_list_links_base &&)=delete | |
Deleted move constructor. More... | |
Public Destructor Index
constexpr | ~double_list_links_base () |
Destruct the node. More... | |
Public Member Functions Index
constexpr void | initialize (void) |
Initialise the node links. More... | |
void | initialize_once (void) |
Initialise the node links only if not already initialised. 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 doubly linked list. More... | |
constexpr double_list_links_base * | next (void) const |
Get the link to the next node. More... | |
double_list_links_base & | operator= (const double_list_links_base &)=delete |
Deleted copy assignment operator. More... | |
double_list_links_base & | operator= (double_list_links_base &&)=delete |
Deleted move assignment operator. More... | |
constexpr double_list_links_base * | 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... | |
Description
A base class for a doubly linked list node.
This class provides a pair of uninitialised pointers to the next and previous elements in a doubly linked list, along with a set of simple (some inlined) methods to access and manipulate these pointers.
Both regular and statically allocated list elements are derived from this class.
Definition at line 112 of file lists.h.
Protected Member Attributes
next_
| protected |
previous_
Public Constructors
double_list_links_base()
| constexpr |
Construct an uninitialised list node.
This must be an empty constructor that does not modify the member pointers, leaving them unchanged. For statically initialised lists, this means both pointers remain as nullptr
, representing an uninitialised state. For regular (dynamically initialised) lists, the derived class constructor will handle the initialisation of the pointers.
This design allows statically allocated objects to be safely zero-initialised at startup (via BSS initialisation), ensuring that the list links are in a known state before any constructors run. It also avoids unnecessary writes for statically allocated objects.
Code analysis tools may report:
- Member
previous_
was not initialized in constructor - Member
next_
was not initialized in constructor These warnings are expected and can be safely ignored in this context.
- The rule of five
The copy constructor, move constructor, copy assignment operator, and move assignment operator are explicitly deleted to prevent accidental copying or moving of intrusive_list objects. This ensures the integrity of the list structure, as duplicating or moving lists could result in invalid or inconsistent links within the list.
Declaration at line 118 of file lists.h, definition at line 75 of file lists-inlines.h.
double_list_links_base()
| delete |
double_list_links_base()
| delete |
Public Destructor
~double_list_links_base()
| constexpr |
Destruct the node.
This must be an empty destructor that does not modify or reset the member pointers, leaving them unchanged. For both statically and dynamically allocated lists, the destructor does not perform any cleanup or pointer manipulation, as the list management is handled elsewhere.
This design avoids unnecessary writes or side effects during object destruction, which is especially important for statically allocated objects or when list nodes may be reused or re-initialised after destruction.
Declaration at line 167 of file lists.h, definition at line 93 of file lists-inlines.h.
Public Member Functions
initialize()
| constexpr |
Initialise the node links.
- Parameters
None.
- Returns
Nothing.
Sets both the previous_
and next_
pointers to point to this node itself, marking the node as unlinked. This state is used to indicate that the node is not currently part of any list.
This method is called during initialisation and after a node is unlinked from a list, ensuring the node is in a safe, standalone state and cannot be traversed as part of a list.
After unlinking a node from a list, it must be returned to this state to prevent accidental access through stale links.
Declaration at line 189 of file lists.h, definition at line 113 of file lists-inlines.h.
initialize_once()
|
Initialise the node links only if not already initialised.
- Parameters
None.
- Returns
Nothing.
If the statically allocated list is still in the initial uninitialised state (with both pointers nullptr
), this method initialises 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 a statically allocated list before inserting elements or performing any other operations.
Declaration at line 200 of file lists.h, definition at line 83 of file lists.cpp.
link_next()
|
Link the new node as next.
- Parameters
[in] node Pointer to the node to be linked as next.
- Returns
Nothing.
Insert the new node between the next pointer and the node pointed by it. This operation is used by lists to link new nodes to the list head. The new node's previous_
pointer is set to the current node, and its next_
pointer is set to the current node's next_
. The neighbouring nodes are updated to point to the new node, maintaining the integrity of the double-linked list.
Declaration at line 210 of file lists.h, definition at line 101 of file lists.cpp.
link_previous()
|
Link the new node as previous.
- Parameters
[in] node Pointer to the node to be linked as previous.
- 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. The new node's next_
pointer is set to the current node, and its previous_
pointer is set to the current node's previous_
. The neighbouring nodes are updated to point to the new node, maintaining the integrity of the double-linked list.
Declaration at line 220 of file lists.h, definition at line 127 of file lists.cpp.
linked()
|
Check if the node is linked to a doubly linked list.
- Parameters
None.
- Return Values
true The node is linked with both pointers. false The node is not linked.
To be linked, both pointers must point to different nodes than itself (double list requirement). If either next_
or previous_
points to this
, the node is considered unlinked (empty state). This method checks the node's linkage status for safe list operations.
Declaration at line 242 of file lists.h, definition at line 176 of file lists.cpp.
next()
| constexpr |
Get the link to the next node.
- Parameters
None.
- Return Values
Pointer to the next node.
Returns a pointer to the next node in the list. If this node is the last in the list, the returned pointer may refer back to the list's sentinel node (for example, the links node in the list container) or to itself if the list is empty.
The returned pointer is of type double_list_links_base*
and may need to be cast to the appropriate derived type by the caller.
Declaration at line 252 of file lists.h, definition at line 137 of file lists-inlines.h.
operator=()
| delete |
operator=()
| delete |
previous()
| constexpr |
Get the link to the previous node.
- Parameters
None.
- Return Values
Pointer to the previous node.
Returns a pointer to the previous node in the list. If this node is the first in the list, the returned pointer may refer back to the list's sentinel node (such as the links node in the list container) or to itself if the list is empty.
The returned pointer is of type double_list_links_base*
and may need to be cast to the appropriate derived type by the caller.
Declaration at line 262 of file lists.h, definition at line 154 of file lists-inlines.h.
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 its pointers set to nullptr
. Only statically allocated nodes in their initial state are considered uninitialized. Regular (dynamically or automatically allocated) nodes are always initialized during construction, so this method will only return true
for statically allocated nodes that have not yet been initialized.
Declaration at line 178 of file lists.h, definition at line 58 of file lists.cpp.
unlink()
|
Remove this node from the list.
- Parameters
None.
- Returns
Nothing.
Update both neighbours to point to each other, effectively removing the node from the list. The node is then returned to the initial state (empty), with both pointers pointing to itself. This operation is safe to call even if the node is already unlinked.
Declaration at line 231 of file lists.h, definition at line 151 of file lists.cpp.
The documentation for this class was generated from the following files:
Generated via docusaurus-plugin-doxygen by Doxygen 1.13.2