RTEMS: Chain Handler

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Chain Handler
Internal » SuperCore

Provides Data Structures Chain Node and Chain Control. More...

## Files
file | chain.h
| Chain Handler API.
file | chainimpl.h
| Chain Handler API.
file | chain.c
| Initialize a Chain Header.

## Data Structures
struct | Chain_Node_struct
struct | Chain_Control
struct | Chain_Iterator
| A chain iterator which is updated during node extraction if it is properly registered. More...
struct | Chain_Iterator_registry
| A registry for chain iterators. More...

## Macros
#define | CHAIN_INITIALIZER_EMPTY(name) { { { &(name).Tail.Node, NULL }, &(name).Head.Node } }
| Chain initializer for an empty chain with designator name.
#define | CHAIN_INITIALIZER_ONE_NODE(node) { { { (node), NULL }, (node) } }
| Chain initializer for a chain with one node.
#define | CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN(chain) { &(chain)->Tail.Node, &(chain)->Head.Node }
| Chain node initializer for a chain containing exactly this node.
#define | CHAIN_DEFINE_EMPTY(name) Chain_Control name = CHAIN_INITIALIZER_EMPTY(name)
| Chain definition for an empty chain with designator name.
#define | CHAIN_ITERATOR_REGISTRY_INITIALIZER(name) { CHAIN_INITIALIZER_EMPTY( name.Iterators ) }
| Chain iterator registry initializer for static initialization.

## Typedefs
typedef struct Chain_Node_struct | Chain_Node
typedef bool(* | Chain_Node_order) (const void *left, const Chain_Node *right)
| Chain node order.

## Enumerations
enum | Chain_Iterator_direction { CHAIN_ITERATOR_FORWARD , CHAIN_ITERATOR_BACKWARD }
| The chain iterator direction. More...

## Functions
void | _Chain_Initialize (Chain_Control *the_chain, void *starting_address, size_t number_nodes, size_t node_size)
| Initializes a chain header.
size_t | _Chain_Node_count_unprotected (const Chain_Control *chain)
| Returns the node count of the chain.
RTEMS_INLINE_ROUTINE void | _Chain_Set_off_chain (Chain_Node *node)
| Sets off chain.
RTEMS_INLINE_ROUTINE void | _Chain_Initialize_node (Chain_Node *the_node)
| Initializes a chain node.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_node_off_chain (const Chain_Node *node)
| Checks if the node is off chain.
RTEMS_INLINE_ROUTINE bool | _Chain_Are_nodes_equal (const Chain_Node *left, const Chain_Node *right)
| Checks if two nodes are equal.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_null_node (const Chain_Node *the_node)
| Checks if the chain node pointer is NULL.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Head (Chain_Control *the_chain)
| Returns pointer to chain head.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_head (const Chain_Control *the_chain)
| Returns pointer to immutable chain head.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Tail (Chain_Control *the_chain)
| Returns pointer to chain tail.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_tail (const Chain_Control *the_chain)
| Returns pointer to immutable chain tail.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_First (const Chain_Control *the_chain)
| Returns pointer to chain's first node.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_first (const Chain_Control *the_chain)
| Returns pointer to immutable chain's first node.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Last (const Chain_Control *the_chain)
| Returns pointer to chain's last node.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_last (const Chain_Control *the_chain)
| Returns pointer to immutable chain's last node.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Next (const Chain_Node *the_node)
| Returns pointer to the next node from this node.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_next (const Chain_Node *the_node)
| Returns pointer to the immutable next node from this node.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Previous (const Chain_Node *the_node)
| Returns pointer to the previous node from this node.
RTEMS_INLINE_ROUTINE const Chain_Node * | _Chain_Immutable_previous (const Chain_Node *the_node)
| Returns pointer to the immutable previous node from this node.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_empty (const Chain_Control *the_chain)
| Checks if the chain is empty.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_first (const Chain_Node *the_node)
| Checks if this is the first node on the chain.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_last (const Chain_Node *the_node)
| Checks if this is the last node on the chain.
RTEMS_INLINE_ROUTINE bool | _Chain_Has_only_one_node (const Chain_Control *the_chain)
| Checks if this chain has only one node.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_head (const Chain_Control *the_chain, const Chain_Node *the_node)
| Checks if this node is the chain head.
RTEMS_INLINE_ROUTINE bool | _Chain_Is_tail (const Chain_Control *the_chain, const Chain_Node *the_node)
| Checks if this node is the chain tail.
RTEMS_INLINE_ROUTINE void | _Chain_Initialize_empty (Chain_Control *the_chain)
| Initializes this chain as empty.
RTEMS_INLINE_ROUTINE void | _Chain_Initialize_one (Chain_Control *the_chain, Chain_Node *the_node)
| Initializes this chain to contain exactly the specified node.
RTEMS_INLINE_ROUTINE void | _Chain_Extract_unprotected (Chain_Node *the_node)
| Extracts this node (unprotected).
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Get_first_unprotected (Chain_Control *the_chain)
| Gets the first node (unprotected).
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Get_unprotected (Chain_Control *the_chain)
| Gets the first node (unprotected).
RTEMS_INLINE_ROUTINE void | _Chain_Insert_unprotected (Chain_Node *after_node, Chain_Node *the_node)
| Inserts a node (unprotected).
RTEMS_INLINE_ROUTINE void | _Chain_Append_unprotected (Chain_Control *the_chain, Chain_Node *the_node)
| Appends a node (unprotected).
RTEMS_INLINE_ROUTINE void | _Chain_Append_if_is_off_chain_unprotected (Chain_Control *the_chain, Chain_Node *the_node)
| Appends a node on the end of a chain if the node is in the off chain state (unprotected).
RTEMS_INLINE_ROUTINE void | _Chain_Prepend_unprotected (Chain_Control *the_chain, Chain_Node *the_node)
| Prepends a node (unprotected).
RTEMS_INLINE_ROUTINE bool | _Chain_Append_with_empty_check_unprotected (Chain_Control *the_chain, Chain_Node *the_node)
| Appends a node and checks if the chain was empty before (unprotected).
RTEMS_INLINE_ROUTINE bool | _Chain_Prepend_with_empty_check_unprotected (Chain_Control *the_chain, Chain_Node *the_node)
| Prepends a node and checks if the chain was empty before (unprotected).
RTEMS_INLINE_ROUTINE bool | _Chain_Get_with_empty_check_unprotected (Chain_Control *the_chain, Chain_Node **the_node)
| Gets the first node and checks if the chain is empty afterwards (unprotected).
RTEMS_INLINE_ROUTINE void | _Chain_Insert_ordered_unprotected (Chain_Control *the_chain, Chain_Node *to_insert, const void *left, Chain_Node_order order)
| Inserts a node into the chain according to the order relation.
RTEMS_INLINE_ROUTINE void | _Chain_Iterator_registry_initialize (Chain_Iterator_registry *the_registry)
| Initializes a chain iterator registry.
RTEMS_INLINE_ROUTINE void | _Chain_Iterator_registry_update (Chain_Iterator_registry *the_registry, Chain_Node *the_node_to_extract)
| Updates all iterators present in the chain iterator registry in case of a node extraction.
RTEMS_INLINE_ROUTINE void | _Chain_Iterator_initialize (Chain_Control *the_chain, Chain_Iterator_registry *the_registry, Chain_Iterator *the_iterator, Chain_Iterator_direction direction)
| Initializes the chain iterator.
RTEMS_INLINE_ROUTINE Chain_Node * | _Chain_Iterator_next (const Chain_Iterator *the_iterator)
| Returns the next node in the iterator direction.
RTEMS_INLINE_ROUTINE void | _Chain_Iterator_set_position (Chain_Iterator *the_iterator, Chain_Node *the_node)
| Sets the iterator position.
RTEMS_INLINE_ROUTINE void | _Chain_Iterator_destroy (Chain_Iterator *the_iterator)
| Destroys the iterator.

## Detailed Description

Provides Data Structures Chain Node and Chain Control.

The Chain Handler is used to manage sets of entities. This handler provides two data structures. The Chain Node data structure is included as the first part of every data structure that will be placed on a chain. The second data structure is Chain Control which is used to manage a set of Chain Nodes.

## Macro Definition Documentation

## ◆ CHAIN_INITIALIZER_ONE_NODE

#define CHAIN_INITIALIZER_ONE_NODE | ( |  | node | ) | { { { (node), NULL }, (node) } }

Chain initializer for a chain with one node.

See also
  CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN().

## ◆ CHAIN_ITERATOR_REGISTRY_INITIALIZER

#define CHAIN_ITERATOR_REGISTRY_INITIALIZER | ( |  | name | ) | { CHAIN_INITIALIZER_EMPTY( name.Iterators ) }

Chain iterator registry initializer for static initialization.

Parameters

  name | The designator of the chain iterator registry.

## ◆ CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN

#define CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN | ( |  | chain | ) | { &(chain)->Tail.Node, &(chain)->Head.Node }

Chain node initializer for a chain containing exactly this node.

See also
  CHAIN_INITIALIZER_ONE_NODE().

## Typedef Documentation

## ◆ Chain_Node

Chain_Node

This type definition promotes the name for the Chain Node used by all RTEMS code. It is a separate type definition because a forward reference is required to define it. See Chain_Node_struct for detailed information.

## ◆ Chain_Node_order

typedef bool(* Chain_Node_order) (const void *left, const Chain_Node *right)

Chain node order.

Parameters

  left | The left hand side.
  right | The right hand side.

Return values

  true | According to the order the left node precedes the right node.
  false | Otherwise.

## Enumeration Type Documentation

## ◆ Chain_Iterator_direction

enum Chain_Iterator_direction

The chain iterator direction.

Enumerator
CHAIN_ITERATOR_FORWARD | Iteration from head to tail.
CHAIN_ITERATOR_BACKWARD | Iteration from tail to head.

## Function Documentation

## ◆ _Chain_Append_if_is_off_chain_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Append_if_is_off_chain_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Appends a node on the end of a chain if the node is in the off chain state (unprotected).

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [in,out] | the_node | The node to be appended if it is in the off chain.

Note
  It does NOT disable interrupts to ensure the atomicity of the append operation.

See also
  _Chain_Append_unprotected() and _Chain_Is_node_off_chain().

## ◆ _Chain_Append_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Appends a node (unprotected).

This routine appends the_node onto the end of the_chain.

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [out] | the_node | The node to be appended to the end of the_chain.

Note
  It does NOT disable interrupts to ensure the atomicity of the append operation.

## ◆ _Chain_Append_with_empty_check_unprotected()

RTEMS_INLINE_ROUTINE bool _Chain_Append_with_empty_check_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Appends a node and checks if the chain was empty before (unprotected).

This routine appends the_node onto the end of the_chain.

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [out] | the_node | The node to be appended to the end of the_chain.

Note
  It does NOT disable interrupts to ensure the atomicity of the append operation.

Return values

  true | The chain was empty before.
  false | The chain contained at least one node before.

## ◆ _Chain_Are_nodes_equal()

RTEMS_INLINE_ROUTINE bool _Chain_Are_nodes_equal | ( | const Chain_Node * | left,
|  | const Chain_Node * | right
| ) |  |

Checks if two nodes are equal.

This function returns true if left and right are equal, and false otherwise.

Parameters

  left | The node on the left hand side of the comparison.
  right | The node on the right hand side of the comparison.

Return values

  true | left and right are equal.
  false | left and right are not equal.

## ◆ _Chain_Extract_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected | ( | Chain_Node * | the_node | ) |

Extracts this node (unprotected).

This routine extracts the_node from the chain on which it resides. It does NOT disable interrupts to ensure the atomicity of the extract operation.

Parameters

  [out] | the_node | The node to be extracted.

## ◆ _Chain_First()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_First | ( | const Chain_Control * | the_chain | ) |

Returns pointer to chain's first node.

This function returns a pointer to the first node on the chain after the head.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the first node of the chain.

## ◆ _Chain_Get_first_unprotected()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Get_first_unprotected | ( | Chain_Control * | the_chain | ) |

Gets the first node (unprotected).

This function removes the first node from the_chain and returns a pointer to that node. It does NOT disable interrupts to ensure the atomicity of the get operation.

Parameters

  [in,out] | the_chain | The chain to attempt to get the first node from.

Returns
  This method returns the first node on the chain even if it is the Chain Tail.

Note
  This routine assumes that there is at least one node on the chain and always returns a node even if it is the Chain Tail.

## ◆ _Chain_Get_unprotected()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Get_unprotected | ( | Chain_Control * | the_chain | ) |

Gets the first node (unprotected).

This function removes the first node from the_chain and returns a pointer to that node. If the_chain is empty, then NULL is returned.

Parameters

  [in,out] | the_chain | The chain to attempt to get the first node from.

Return values

  pointer | Pointer to the first node. The chain contained at least one node.
  NULL | The chain is empty.

Note
  It does NOT disable interrupts to ensure the atomicity of the get operation.

## ◆ _Chain_Get_with_empty_check_unprotected()

RTEMS_INLINE_ROUTINE bool _Chain_Get_with_empty_check_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node ** | the_node
| ) |  |

Gets the first node and checks if the chain is empty afterwards (unprotected).

This function removes the first node from the_chain and returns a pointer to that node in the_node. If the_chain is empty, then NULL is returned.

Parameters

  [in,out] | the_chain | The chain to attempt to get the first node from.
  [out] | the_node | The first node on the chain or NULL if the chain is empty.

Note
  It does NOT disable interrupts to ensure the atomicity of the get operation.

Return values

  true | The chain is empty now.
  false | The chain contains at least one node now.

## ◆ _Chain_Has_only_one_node()

RTEMS_INLINE_ROUTINE bool _Chain_Has_only_one_node | ( | const Chain_Control * | the_chain | ) |

Checks if this chain has only one node.

This function returns true if there is only one node on the_chain and false otherwise.

Parameters

  the_chain | is the chain to be operated upon.

Return values

  true | There is only one node on the_chain.
  false | There is more than one node on the_chain.

## ◆ _Chain_Head()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Head | ( | Chain_Control * | the_chain | ) |

Returns pointer to chain head.

This function returns a pointer to the head node on the chain.

Parameters

  [in] | the_chain | The chain to be operated upon.

Returns
  This method returns the permanent head node of the chain.

## ◆ _Chain_Immutable_first()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_first | ( | const Chain_Control * | the_chain | ) |

Returns pointer to immutable chain's first node.

This function returns a pointer to the first node on the chain after the head.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the first node of the chain.

## ◆ _Chain_Immutable_head()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_head | ( | const Chain_Control * | the_chain | ) |

Returns pointer to immutable chain head.

This function returns a pointer to the head node on the chain.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the permanent head node of the chain.

## ◆ _Chain_Immutable_last()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_last | ( | const Chain_Control * | the_chain | ) |

Returns pointer to immutable chain's last node.

This function returns a pointer to the last node on the chain just before the tail.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the last node of the chain.

## ◆ _Chain_Immutable_next()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_next | ( | const Chain_Node * | the_node | ) |

Returns pointer to the immutable next node from this node.

This function returns a pointer to the next node after this node.

Parameters

  the_node | The node to be operated upon.

Returns
  This method returns the next node on the chain.

## ◆ _Chain_Immutable_previous()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_previous | ( | const Chain_Node * | the_node | ) |

Returns pointer to the immutable previous node from this node.

This function returns a pointer to the previous node on this chain.

Parameters

  the_node | The node to be operated upon.

Returns
  This method returns the previous node on the chain.

## ◆ _Chain_Immutable_tail()

RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_tail | ( | const Chain_Control * | the_chain | ) |

Returns pointer to immutable chain tail.

This function returns a pointer to the tail node on the chain.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the permanent tail node of the chain.

## ◆ _Chain_Initialize()

void _Chain_Initialize | ( | Chain_Control * | the_chain,
|  | void * | starting_address,
|  | size_t | number_nodes,
|  | size_t | node_size
| ) |  |

Initializes a chain header.

This routine initializes the_chain structure to manage the contiguous array of number_nodes nodes which starts at starting_address. Each node is of node_size bytes.

Parameters

  [out] | the_chain | Specifies the chain to initialize.
  | starting_address | The starting address of the array of elements.
  | number_nodes | The number of nodes that will be in the chain.
  | node_size | The size of each node.

## ◆ _Chain_Initialize_empty()

RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty | ( | Chain_Control * | the_chain | ) |

Initializes this chain as empty.

This routine initializes the specified chain to contain zero nodes.

Parameters

  [out] | the_chain | The chain to be initialized.

## ◆ _Chain_Initialize_node()

RTEMS_INLINE_ROUTINE void _Chain_Initialize_node | ( | Chain_Node * | the_node | ) |

Initializes a chain node.

In debug configurations, the node is set off chain. In all other configurations, this function does nothing.

Parameters

  [out] | the_node | The chain node to initialize.

## ◆ _Chain_Initialize_one()

RTEMS_INLINE_ROUTINE void _Chain_Initialize_one | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Initializes this chain to contain exactly the specified node.

Parameters

  [out] | the_chain | The chain to be initialized to contain exactly the specified node.
  [out] | the_node | The one and only node of the chain to be initialized.

## ◆ _Chain_Insert_ordered_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Insert_ordered_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | to_insert,
|  | const void * | left,
|  | Chain_Node_order | order
| ) |  |

Inserts a node into the chain according to the order relation.

After the operation the chain contains the node to insert and the order relation holds for all nodes from the head up to the inserted node. Nodes after the inserted node are not moved.

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [out] | to_insert | The node to insert.
  | left | The left hand side passed to the order relation. It must correspond to the node to insert. The separate left hand side parameter may help the compiler to generate better code if it is stored in a local variable.
  | order | The order relation.

## ◆ _Chain_Insert_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected | ( | Chain_Node * | after_node,
|  | Chain_Node * | the_node
| ) |  |

Inserts a node (unprotected).

This routine inserts the_node on a chain immediately following after_node.

Parameters

  [in,out] | after_node | The node which will precede the_node on the chain.
  [out] | the_node | The node to be inserted after after_node.

Note
  It does NOT disable interrupts to ensure the atomicity of the extract operation.

## ◆ _Chain_Is_empty()

RTEMS_INLINE_ROUTINE bool _Chain_Is_empty | ( | const Chain_Control * | the_chain | ) |

Checks if the chain is empty.

This function returns true if there are no nodes on the_chain and false otherwise.

Parameters

  the_chain | The chain to check if it is empty.

Return values

  true | There are no nodes on the_chain.
  false | There are nodes on the_chain.

## ◆ _Chain_Is_first()

RTEMS_INLINE_ROUTINE bool _Chain_Is_first | ( | const Chain_Node * | the_node | ) |

Checks if this is the first node on the chain.

This function returns true if the_node is the first node on a chain and false otherwise.

Parameters

  the_node | The node of which the caller wants to know if it is the first node on a chain.

Return values

  true | the_node is the first node on a chain.
  false | the_node is not the first node on a chain.

## ◆ _Chain_Is_head()

RTEMS_INLINE_ROUTINE bool _Chain_Is_head | ( | const Chain_Control * | the_chain,
|  | const Chain_Node * | the_node
| ) |  |

Checks if this node is the chain head.

This function returns true if the_node is the head of the_chain and false otherwise.

Parameters

  the_chain | The chain to be operated upon.
  the_node | The node to check for being the Chain Head.

Return values

  true | the_node is the head of the_chain.
  false | the_node is not the head of the_chain.

## ◆ _Chain_Is_last()

RTEMS_INLINE_ROUTINE bool _Chain_Is_last | ( | const Chain_Node * | the_node | ) |

Checks if this is the last node on the chain.

This function returns true if the_node is the last node on a chain and false otherwise.

Parameters

  the_node | The node of which the caller wants to know if it is the last node on a chain.

Return values

  true | the_node is the last node on a chain.
  false | the_node is not the last node on a chain.

## ◆ _Chain_Is_node_off_chain()

RTEMS_INLINE_ROUTINE bool _Chain_Is_node_off_chain | ( | const Chain_Node * | node | ) |

Checks if the node is off chain.

This function returns true if the node is not on a chain. A node is off chain if the next field is set to NULL.

Parameters

  node | The node to check if it is off chain.

Return values

  true | The node is off chain.
  false | The node is not off chain.

## ◆ _Chain_Is_null_node()

RTEMS_INLINE_ROUTINE bool _Chain_Is_null_node | ( | const Chain_Node * | the_node | ) |

Checks if the chain node pointer is NULL.

This function returns true if the_node is NULL and false otherwise.

Parameters

  the_node | The node pointer to check.

Return values

  true | the_node is `NULL`.
  false | the_node is not `NULL`.

## ◆ _Chain_Is_tail()

RTEMS_INLINE_ROUTINE bool _Chain_Is_tail | ( | const Chain_Control * | the_chain,
|  | const Chain_Node * | the_node
| ) |  |

Checks if this node is the chain tail.

This function returns true if the_node is the tail of the_chain and false otherwise.

Parameters

  the_chain | The chain to be operated upon.
  the_node | The node to check for being the Chain Tail.

Return values

  true | the_node is the tail of the_chain.
  false | the_node is not the tail of the_chain.

## ◆ _Chain_Iterator_destroy()

RTEMS_INLINE_ROUTINE void _Chain_Iterator_destroy | ( | Chain_Iterator * | the_iterator | ) |

Destroys the iterator.

Removes the iterator from its registry.

Parameters

  [out] | the_iterator | The chain iterator.

## ◆ _Chain_Iterator_initialize()

RTEMS_INLINE_ROUTINE void _Chain_Iterator_initialize | ( | Chain_Control * | the_chain,
|  | Chain_Iterator_registry * | the_registry,
|  | Chain_Iterator * | the_iterator,
|  | Chain_Iterator_direction | direction
| ) |  |

Initializes the chain iterator.

In the following example nodes inserted during the iteration are visited in case they are inserted after the current position in iteration order.

#include <rtems/score/chainimpl.h>
#include <rtems/score/isrlock.h>
typedef struct {
Chain_Control Chain;
Chain_Iterator_registry Iterators;
ISR_LOCK_MEMBER( Lock )
} Some_Control;
void iterate(
Some_Control *the_some,
void ( *visitor )( Chain_Node * )
)
{
ISR_lock_Context lock_context;
Chain_Iterator iter;
Chain_Node *node;
const Chain_Node *end;
end = _Chain_Immutable_tail( &the_some->Chain );
_ISR_lock_ISR_disable_and_acquire( &the_some->Lock, &lock_context );
_Chain_Iterator_initialize(
&the_some->Chain,
&the_some->Iterators,
&iter,
CHAIN_ITERATOR_FORWARD
);
while ( ( node = _Chain_Iterator_next( &iter ) ) != end ) {
_Chain_Iterator_set_position( &iter, node );
_ISR_lock_Release_and_ISR_enable( &the_some->Lock, &lock_context );
( *visitor )( node );
_ISR_lock_ISR_disable_and_acquire( &the_some->Lock, &lock_context );
}
_Chain_Iterator_destroy( &iter );
_ISR_lock_Release_and_ISR_enable( &the_some->Lock, &lock_context );
}
chainimpl.h
Chain Handler API.
_Chain_Immutable_tail
RTEMS_INLINE_ROUTINE const Chain_Node * _Chain_Immutable_tail(const Chain_Control *the_chain)
Returns pointer to immutable chain tail.
Definition: chainimpl.h:243
_Chain_Iterator_set_position
RTEMS_INLINE_ROUTINE void _Chain_Iterator_set_position(Chain_Iterator *the_iterator, Chain_Node *the_node)
Sets the iterator position.
Definition: chainimpl.h:1106
_Chain_Iterator_next
RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Iterator_next(const Chain_Iterator *the_iterator)
Returns the next node in the iterator direction.
Definition: chainimpl.h:1089
_Chain_Iterator_destroy
RTEMS_INLINE_ROUTINE void _Chain_Iterator_destroy(Chain_Iterator *the_iterator)
Destroys the iterator.
Definition: chainimpl.h:1121
_Chain_Iterator_initialize
RTEMS_INLINE_ROUTINE void _Chain_Iterator_initialize(Chain_Control *the_chain, Chain_Iterator_registry *the_registry, Chain_Iterator *the_iterator, Chain_Iterator_direction direction)
Initializes the chain iterator.
Definition: chainimpl.h:1057
CHAIN_ITERATOR_FORWARD
@ CHAIN_ITERATOR_FORWARD
Iteration from head to tail.
Definition: chainimpl.h:888
ISR_LOCK_MEMBER
#define ISR_LOCK_MEMBER(_designator)
Defines an ISR lock member.
Definition: isrlock.h:89
_ISR_lock_Release_and_ISR_enable
#define _ISR_lock_Release_and_ISR_enable(_lock, _context)
Releases an ISR lock.
Definition: isrlock.h:263
_ISR_lock_ISR_disable_and_acquire
#define _ISR_lock_ISR_disable_and_acquire(_lock, _context)
Acquires an ISR lock.
Definition: isrlock.h:238
isrlock.h
ISR Locks.
Chain_Iterator_registry
A registry for chain iterators.
Definition: chainimpl.h:934
Chain_Iterator
A chain iterator which is updated during node extraction if it is properly registered.
Definition: chainimpl.h:902
Chain_Node_struct
Definition: chain.h:68
ISR_lock_Context
Local ISR lock context for acquire and release pairs.
Definition: isrlock.h:65
Chain_Control
Definition: chain.h:86

Parameters

  [out] | the_chain | The chain to iterate.
  [in,out] | the_registry | The registry for the chain iterator.
  [out] | the_iterator | The chain iterator to initialize.
  [out] | direction | The iteration direction.

See also
  _Chain_Iterator_next(), _Chain_Iterator_set_position() and Chain_Iterator_destroy().

Warning
  Think twice before you use a chain iterator. Its current implementation is unfit for use in performance relevant components, due to the linear time complexity in _Chain_Iterator_registry_update().

## ◆ _Chain_Iterator_next()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Iterator_next | ( | const Chain_Iterator * | the_iterator | ) |

Returns the next node in the iterator direction.

In case a next node exists, then the iterator should be updated via _Chain_Iterator_set_position() to continue with the next iteration step.

Parameters

  [in,out] | the_iterator | The chain iterator.

Returns
  The next node in the iterator direction

## ◆ _Chain_Iterator_registry_initialize()

RTEMS_INLINE_ROUTINE void _Chain_Iterator_registry_initialize | ( | Chain_Iterator_registry * | the_registry | ) |

Initializes a chain iterator registry.

Parameters

  [out] | the_registry | The chain iterator registry to be initialized.

## ◆ _Chain_Iterator_registry_update()

RTEMS_INLINE_ROUTINE void _Chain_Iterator_registry_update | ( | Chain_Iterator_registry * | the_registry,
|  | Chain_Node * | the_node_to_extract
| ) |  |

Updates all iterators present in the chain iterator registry in case of a node extraction.

Must be called before _Chain_Extract_unprotected().

Warning
  This function will look at all registered chain iterators to determine if an update is necessary.

Parameters

  [in,out] | the_registry | the chain iterator registry.
  [out] | the_node_to_extract | The node that will be extracted.

## ◆ _Chain_Iterator_set_position()

RTEMS_INLINE_ROUTINE void _Chain_Iterator_set_position | ( | Chain_Iterator * | the_iterator,
|  | Chain_Node * | the_node
| ) |  |

Sets the iterator position.

Parameters

  [out] | the_iterator | The chain iterator.
  [out] | the_node | The new iterator position.

## ◆ _Chain_Last()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Last | ( | const Chain_Control * | the_chain | ) |

Returns pointer to chain's last node.

This function returns a pointer to the last node on the chain just before the tail.

Parameters

  the_chain | The chain to be operated upon.

Returns
  This method returns the last node of the chain.

## ◆ _Chain_Next()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Next | ( | const Chain_Node * | the_node | ) |

Returns pointer to the next node from this node.

This function returns a pointer to the next node after this node.

Parameters

  the_node | The node to be operated upon.

Returns
  This method returns the next node on the chain.

## ◆ _Chain_Node_count_unprotected()

size_t _Chain_Node_count_unprotected | ( | const Chain_Control * | chain | ) |

Returns the node count of the chain.

Parameters

  chain | The chain to return the node count from.

Note
  It does NOT disable interrupts to ensure the atomicity of the operation.

Returns
  The node count of the chain.

## ◆ _Chain_Prepend_unprotected()

RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Prepends a node (unprotected).

This routine prepends the_node onto the front of the_chain.

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [in,out] | the_node | The node to be prepended to the front of the_chain.

Note
  It does NOT disable interrupts to ensure the atomicity of the prepend operation.

## ◆ _Chain_Prepend_with_empty_check_unprotected()

RTEMS_INLINE_ROUTINE bool _Chain_Prepend_with_empty_check_unprotected | ( | Chain_Control * | the_chain,
|  | Chain_Node * | the_node
| ) |  |

Prepends a node and checks if the chain was empty before (unprotected).

This routine prepends the_node onto the front of the_chain.

Parameters

  [in,out] | the_chain | The chain to be operated upon.
  [out] | the_node | The node to be prepended to the front of the_chain.

Note
  It does NOT disable interrupts to ensure the atomicity of the prepend operation.

Return values

  true | The chain was empty before.
  false | The chain contained at least one node before.

## ◆ _Chain_Previous()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Previous | ( | const Chain_Node * | the_node | ) |

Returns pointer to the previous node from this node.

This function returns a pointer to the previous node on this chain.

Parameters

  the_node | The node to be operated upon.

Returns
  This method returns the previous node on the chain.

## ◆ _Chain_Set_off_chain()

RTEMS_INLINE_ROUTINE void _Chain_Set_off_chain | ( | Chain_Node * | node | ) |

Sets off chain.

This function sets the next field of the node to NULL indicating the node is not part of a chain.

Parameters

  [out] | node | The node to set off chain.

## ◆ _Chain_Tail()

RTEMS_INLINE_ROUTINE Chain_Node * _Chain_Tail | ( | Chain_Control * | the_chain | ) |

Returns pointer to chain tail.

This function returns a pointer to the tail node on the chain.

Parameters

  [in] | the_chain | The chain to be operated upon.

Returns
  This method returns the permanent tail node of the chain.