A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd

Intrusive Links

A set of link structures designed to be used within containers such as etl::intrusive_list.
They are parameterised by an id that allows them to be multiply inherited from when creating objects that must exist in
more than one intrusive container.

There are link and unlink functions supplied to manage connections between links. The functions will accept any
permutation of pointer and reference parameters, though reference parameters offer the best performance.
For bidirectional links, unlinking a node will automatically adjust the links of the surrounding nodes at the same level.

Forward link

template <const size_t ID_>
struct forward_link

Template parameters

const size_t ID_ A unique id for this link level.

Public constants

enum ID The unique id for this link level.

Public variables

forward_link<ID>* etl_next A pointer to the next forward link at this level.

Public functions

clear() Clears the pointers to nullptr.

Link functions

void etl::link<type>(lhs, rhs)        Links lhs to rhs.
void etl::link_splice<type>(lhs, rhs) Links lhs to rhs and rhs to what lhs pointed to. lhs must be 
                                      initialised.
void etl::unlink_after(node)          Unlinks the node after node.
void etl::unlink_after(before, lastUnlinks the nodes after before up to and including last.
                                      The range remain linked to each other.

Bidirectional link

template <const size_t ID_>
struct bidirectional_link

Template parameters

const size_t ID_ A unique id for this link level.

Public constants

enum ID     The unique id for this link level.

Public variables

bidirectional_link<ID>* etl_previous A pointer to the previous bidirectional link at this level.
bidirectional_link<ID>* etl_next     A pointer to the next bidirectional link at this level.

Public functions

clear()  Clears the pointers to nullptr.
reverse()Reverses the links.

Link functions

void etl::link<type>(lhs, rhs)
Link lhs to rhs.

void etl::link_splice<type>(lhs, rhs)
Link lhs to rhs and rhs to what lhs pointed to. If lhs is not nullptr then it must be initialised.

void etl::link_splice<type>(lhs, first, last)
Link lhs to the range first, last and last to what lhs pointed to. If lhs is not nullptr then it must be initialised.

void etl_unlink(node)                
Unlink the specified node. Elements either side are joined.

void etl_unlink(first, last)
Unlinks the range of nodes from first to last inclusive.
The range first/last remain linked to each other.

Tree link

template <const size_t ID_>
struct tree_link

Template parameters

const size_t ID_ A unique id for this link level.

Public constants

enum ID The unique id for this link level.

Public variables

tree_link<ID>* etl_parent A pointer to the parent tree link at this level.
tree_link<ID>* etl_left   A pointer to the left tree link at this level.
tree_link<ID>* etl_right  A pointer to the right tree link at this level.

Public functions

clear() Clears the pointers to nullptr.

Link functions

void etl::link_left<type>(parent, leaf)  Links leaf to the left of parent.
void etl::link_right<type>(parent, leaf) Links leaf to the right of parent.

void etl::link_rotate_left<type>(parent, leaf)  Rotates the link left making leaf the new parent.
void etl::link_rotate_right<type>(parent, leaf) Rotates the link right making leaf the new parent.

void etl::link_rotate<type>(parent, leaf) Rotates the link left or right making leaf the new parent.
                                          Chooses left or right rotate depending on the leaf connection.

Example 1

A simple two level intrusive list.


// The link levels
typedef etl::bidirectional_link<0> level0_t;
typedef etl::bidirectional_link<1> level1_t;

// The item stored in the lists
struct item : public level0_t, public level1_t
{
  item(int value)
    :: value(value)
  {
  }

  int value;
};

item data0(0);
item data1(1);
item data2(2);
item data3(3);

etl::intrusive_list<item, level0_t> level0_list;
etl::intrusive_list<item, level1_t> level1_list;

// Add items to level0 list
level0_list.push_back(data0);
level0_list.push_back(data1);
level0_list.push_back(data2);

// Add items to level1 list
level1_list.push_back(data3);
level1_list.push_back(data2);
level1_list.push_back(data1);

Example 2

Manual list manipulation.


typedef etl::bidirectional_link<0> level0_t;
typedef etl::bidirectional_link<1> level1_t;

// The item stored in the lists
struct item : public level0_t, public level1_t
{
  item(int value)
    :: value(value)
  {
  }

  int value;
};

item data0(0);
item data1(1);
item data2(2);
item data3(3);

// Set the first and last nodes links to nullptr.
data0.level0_t::clear();
data3.level0_t::clear();

// Make the links.
etl::link<level0_t>(data0, data1);
etl::link<level0_t>(data1, data2);
etl::link<level0_t>(data2, data3);// Level 0 = data0, data1, data2, data3

// Set the first and last nodes links to nullptr.
data2.level1_t::clear();
data1.level1_t::clear();

// Make the links.
etl::link<level1_t>(data2, data3);
etl::link<level1_t>(data3, data0);
etl::link<level1_t>(data0, data1); // Level 1 = data2, data3, data0, data1

// Disconnect a node.
etl::unlink<level1_t>(data3); // Level 1 = data2, data0, data1
intrusive_links.h