double_list_links Class

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

Declaration

class micro_os_plus::utils::double_list_links { ... }

Included Headers

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

Base class

class	double_list_links_base
	A base class for a doubly linked list node. More...

Public Member Typedefs Index

using	is_statically_allocated = std::false_type
	Type indicating that the links node is not statically allocated. More...

Public Constructors Index

constexpr	double_list_links ()
	Construct a list node (initialise the pointers). More...
	double_list_links (const double_list_links &)=delete
	Deleted copy constructor. More...
	double_list_links (double_list_links &&)=delete
	Deleted move constructor. More...

Public Destructor Index

constexpr	~double_list_links ()
	Destruct the node. More...

Public Operators Index

double_list_links &	operator= (const double_list_links &)=delete
	Deleted copy assignment operator. More...
double_list_links &	operator= (double_list_links &&)=delete
	Deleted move assignment operator. 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...
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...

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...

Description

A class for the core of a doubly linked list (pointers to neighbours).

The double_list_links class provides the fundamental structure for a doubly linked list node, inheriting the pair of pointers to the next and previous elements and the associated access methods from double_list_links_base. The constructor initialises the pointers to form an empty list, where both pointers refer to the node itself.

This class is intended for use as the core linking mechanism within doubly linked lists, supporting efficient insertion and removal operations.

Definition at line 300 of file lists.h.

Public Member Typedefs

is_statically_allocated

using micro_os_plus::utils::double_list_links::is_statically_allocated = std::false_type

Type indicating that the links node is not statically allocated.

Definition at line 307 of file lists.h.

307 using is_statically_allocated = std::false_type;

Public Constructors

double_list_links()

micro_os_plus::utils::double_list_links::double_list_links ()

constexpr

Construct a list node (initialise the pointers).

The constructor for double_list_links is used for regular (non-static) list link nodes. It explicitly initialises the node by calling initialize(), which sets both the previous_ and next_ pointers to point to this node itself, marking it as unlinked and ready for use in a list. This ensures that dynamically allocated or automatic list nodes always start in a known, safe state, regardless of their memory contents prior to construction.

info

For statically allocated nodes, the constructor is intentionally left empty to allow BSS zero-initialisation. For dynamically allocated nodes, explicit initialisation is required to avoid undefined pointer values.

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 312 of file lists.h, definition at line 254 of file lists-inlines.h.

254 constexpr double_list_links::double_list_links ()

255 {

256 // For regular (non static) classes the members

257 // must be explicitly initialised.

258 initialize ();

259 }

Reference micro_os_plus::utils::double_list_links_base::initialize.

Referenced by double_list_links, double_list_links, operator= and operator=.

double_list_links()

micro_os_plus::utils::double_list_links::double_list_links (const double_list_links &)

delete

Deleted copy constructor.

Copying of list node objects is explicitly disallowed to prevent accidental duplication, which could compromise the integrity of the list structure.

Definition at line 324 of file lists.h.

Reference double_list_links.

double_list_links()

micro_os_plus::utils::double_list_links::double_list_links (double_list_links &&)

delete

Deleted move constructor.

Moving of list node objects is explicitly disallowed to avoid invalid or inconsistent links within the list that could result from moving nodes.

Definition at line 333 of file lists.h.

Reference double_list_links.

Public Destructor

~double_list_links()

micro_os_plus::utils::double_list_links::~double_list_links ()

constexpr

Destruct the node.

Destroys the node. No special cleanup is required as the class does not manage resources.

Declaration at line 365 of file lists.h, definition at line 266 of file lists-inlines.h.

266 constexpr double_list_links::~double_list_links ()

267 {

268 }

Public Operators

operator=()

double_list_links & micro_os_plus::utils::double_list_links::operator= (const double_list_links &)

delete

Deleted copy assignment operator.

Copy assignment is explicitly disallowed to prevent accidental overwriting of list node objects, which could lead to corruption of the list structure.

Definition at line 344 of file lists.h.

Reference double_list_links.

operator=()

double_list_links & micro_os_plus::utils::double_list_links::operator= (double_list_links &&)

delete

Deleted move assignment operator.

Move assignment is explicitly disallowed to avoid invalid or inconsistent links within the list that could result from moving nodes.

Definition at line 355 of file lists.h.

Reference double_list_links.

Public Member Functions

initialize()

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

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.

info

After unlinking a node from a list, it must be returned to this state to prevent accidental access through stale links.

Declaration at line 194 of file lists.h, definition at line 113 of file lists-inlines.h.

113 double_list_links_base::initialize (void)

114 {

115 previous_ = this;

116 next_ = this;

117 }

References micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

Referenced by double_list_links, micro_os_plus::utils::double_list_links_base::initialize_once and micro_os_plus::utils::double_list_links_base::unlink.

initialize_once()

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

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.

info

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

Declaration at line 205 of file lists.h, definition at line 83 of file lists.cpp.

83 double_list_links_base::initialize_once (void)

84 {

85 if (uninitialized ())

86 {

87 initialize ();

88 }

89 }

References micro_os_plus::utils::double_list_links_base::initialize and micro_os_plus::utils::double_list_links_base::uninitialized.

link_next()

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

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 215 of file lists.h, definition at line 101 of file lists.cpp.

101 double_list_links_base::link_next (double_list_links_base* node)

102 {

103#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS)

104 trace::printf ("%s() link %p after %p\n", __func__, node, this);

105#endif

106 assert (next_ != nullptr);

107 assert (next_->previous_ != nullptr);

108

109 // Make the new node point to its new neighbours.

110 node->previous_ = this;

111 node->next_ = next_;

112

113 next_->previous_ = node;

114 next_ = node;

115 }

References micro_os_plus::utils::double_list_links_base::double_list_links_base, micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

link_previous()

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

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 225 of file lists.h, definition at line 127 of file lists.cpp.

127 double_list_links_base::link_previous (double_list_links_base* node)

128 {

129#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS)

130 trace::printf ("%s() link %p before %p\n", __func__, node, this);

131#endif

132 assert (next_ != nullptr);

133 assert (next_->previous_ != nullptr);

134

135 // Make the new node point to its new neighbours.

136 node->next_ = this;

137 node->previous_ = previous_;

138

139 previous_->next_ = node;

140 previous_ = node;

141 }

References micro_os_plus::utils::double_list_links_base::double_list_links_base, micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

linked()

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

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 247 of file lists.h, definition at line 176 of file lists.cpp.

176 double_list_links_base::linked (void) const

177 {

178 if (next_ == this || previous_ == this)

179 {

180 assert (next_ == this);

181 assert (previous_ == this);

182 return false;

183 }

184 return true;

185 }

References micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

next()

double_list_links_base * micro_os_plus::utils::double_list_links_base::next (void)

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.

info

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 257 of file lists.h, definition at line 137 of file lists-inlines.h.

137 double_list_links_base::next (void) const

138 {

139 return next_;

140 }

Reference micro_os_plus::utils::double_list_links_base::next_.

previous()

double_list_links_base * micro_os_plus::utils::double_list_links_base::previous (void)

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.

info

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 267 of file lists.h, definition at line 154 of file lists-inlines.h.

154 double_list_links_base::previous (void) const

155 {

156 return previous_;

157 }

Reference micro_os_plus::utils::double_list_links_base::previous_.

uninitialized()

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

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 183 of file lists.h, definition at line 58 of file lists.cpp.

58 double_list_links_base::uninitialized (void) const

59 {

60 if (previous_ == nullptr || next_ == nullptr)

61 {

62 assert (previous_ == nullptr);

63 assert (next_ == nullptr);

64 return true;

65 }

66 return false;

67 }

References micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

Referenced by micro_os_plus::utils::double_list_links_base::initialize_once.

unlink()

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

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 236 of file lists.h, definition at line 151 of file lists.cpp.

151 double_list_links_base::unlink (void)

152 {

153#if defined(MICRO_OS_PLUS_TRACE_UTILS_LISTS)

154 trace::printf ("%s() %p \n", __func__, this);

155#endif

156

157 // Make neighbours point to each other.

158 // This works even if the node is already unlinked,

159 // so no need for an extra test.

160 previous_->next_ = next_;

161 next_->previous_ = previous_;

162

163 // Reset the unlinked node to the initial state,

164 // with both pointers pointing to itself.

165 initialize ();

166 }

References micro_os_plus::utils::double_list_links_base::initialize, micro_os_plus::utils::double_list_links_base::next_ and micro_os_plus::utils::double_list_links_base::previous_.

Protected Member Attributes

next_

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

protected

Pointer to the next node.

Definition at line 278 of file lists.h.

278 double_list_links_base* next_;

Referenced by micro_os_plus::utils::double_list_links_base::initialize, micro_os_plus::utils::double_list_links_base::link_next, micro_os_plus::utils::double_list_links_base::link_previous, micro_os_plus::utils::double_list_links_base::linked, micro_os_plus::utils::double_list_links_base::next, micro_os_plus::utils::static_double_list_links::nullify, micro_os_plus::utils::double_list_links_base::uninitialized and micro_os_plus::utils::double_list_links_base::unlink.

previous_

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

protected

Pointer to the previous node.

Definition at line 273 of file lists.h.

273 double_list_links_base* previous_;

Referenced by micro_os_plus::utils::double_list_links_base::initialize, micro_os_plus::utils::double_list_links_base::link_next, micro_os_plus::utils::double_list_links_base::link_previous, micro_os_plus::utils::double_list_links_base::linked, micro_os_plus::utils::static_double_list_links::nullify, micro_os_plus::utils::double_list_links_base::previous, micro_os_plus::utils::double_list_links_base::uninitialized and micro_os_plus::utils::double_list_links_base::unlink.

---

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

• lists-inlines.h
• lists.h
• lists.cpp

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.14.0.