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.

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

#define	CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN(chain) { &(chain)->Tail.Node, &(chain)->Head.Node }
	Chain node initializer for a chain containing exactly this node. More...

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

Typedefs
typedef struct Chain_Node_struct	Chain_Node

typedef bool(*	Chain_Node_order) (const void left, const Chain_Node right)
	Chain node order. More...

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

size_t	_Chain_Node_count_unprotected (const Chain_Control *chain)
	Returns the node count of the chain. More...

static __inline__ void	_Chain_Set_off_chain (Chain_Node *node)
	Sets off chain. More...

static __inline__ void	_Chain_Initialize_node (Chain_Node *the_node)
	Initializes a chain node. More...

static __inline__ bool	_Chain_Is_node_off_chain (const Chain_Node *node)
	Checks if the node is off chain. More...

static __inline__ bool	_Chain_Are_nodes_equal (const Chain_Node left, const Chain_Node right)
	Checks if two nodes are equal. More...

static __inline__ bool	_Chain_Is_null_node (const Chain_Node *the_node)
	Checks if the chain node pointer is NULL. More...

static __inline__ Chain_Node *	_Chain_Head (Chain_Control *the_chain)
	Returns pointer to chain head. More...

static __inline__ const Chain_Node *	_Chain_Immutable_head (const Chain_Control *the_chain)
	Returns pointer to immutable chain head. More...

static __inline__ Chain_Node *	_Chain_Tail (Chain_Control *the_chain)
	Returns pointer to chain tail. More...

static __inline__ const Chain_Node *	_Chain_Immutable_tail (const Chain_Control *the_chain)
	Returns pointer to immutable chain tail. More...

static __inline__ Chain_Node *	_Chain_First (const Chain_Control *the_chain)
	Returns pointer to chain's first node. More...

static __inline__ const Chain_Node *	_Chain_Immutable_first (const Chain_Control *the_chain)
	Returns pointer to immutable chain's first node. More...

static __inline__ Chain_Node *	_Chain_Last (const Chain_Control *the_chain)
	Returns pointer to chain's last node. More...

static __inline__ const Chain_Node *	_Chain_Immutable_last (const Chain_Control *the_chain)
	Returns pointer to immutable chain's last node. More...

static __inline__ Chain_Node *	_Chain_Next (const Chain_Node *the_node)
	Returns pointer to the next node from this node. More...

static __inline__ const Chain_Node *	_Chain_Immutable_next (const Chain_Node *the_node)
	Returns pointer to the immutable next node from this node. More...

static __inline__ Chain_Node *	_Chain_Previous (const Chain_Node *the_node)
	Returns pointer to the previous node from this node. More...

static __inline__ const Chain_Node *	_Chain_Immutable_previous (const Chain_Node *the_node)
	Returns pointer to the immutable previous node from this node. More...

static __inline__ bool	_Chain_Is_empty (const Chain_Control *the_chain)
	Checks if the chain is empty. More...

static __inline__ bool	_Chain_Is_first (const Chain_Node *the_node)
	Checks if this is the first node on the chain. More...

static __inline__ bool	_Chain_Is_last (const Chain_Node *the_node)
	Checks if this is the last node on the chain. More...

static __inline__ bool	_Chain_Has_only_one_node (const Chain_Control *the_chain)
	Checks if this chain has only one node. More...

static __inline__ bool	_Chain_Is_head (const Chain_Control the_chain, const Chain_Node the_node)
	Checks if this node is the chain head. More...

static __inline__ bool	_Chain_Is_tail (const Chain_Control the_chain, const Chain_Node the_node)
	Checks if this node is the chain tail. More...

static __inline__ void	_Chain_Initialize_empty (Chain_Control *the_chain)
	Initializes this chain as empty. More...

static __inline__ void	_Chain_Initialize_one (Chain_Control the_chain, Chain_Node the_node)
	Initializes this chain to contain exactly the specified node. More...

static __inline__ void	_Chain_Extract_unprotected (Chain_Node *the_node)
	Extracts this node (unprotected). More...

static __inline__ Chain_Node *	_Chain_Get_first_unprotected (Chain_Control *the_chain)
	Gets the first node (unprotected). More...

static __inline__ Chain_Node *	_Chain_Get_unprotected (Chain_Control *the_chain)
	Gets the first node (unprotected). More...

static __inline__ void	_Chain_Insert_unprotected (Chain_Node after_node, Chain_Node the_node)
	Inserts a node (unprotected). More...

static __inline__ void	_Chain_Append_unprotected (Chain_Control the_chain, Chain_Node the_node)
	Appends a node (unprotected). More...

static __inline__ 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). More...

static __inline__ void	_Chain_Prepend_unprotected (Chain_Control the_chain, Chain_Node the_node)
	Prepends a node (unprotected). More...

static __inline__ 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). More...

static __inline__ 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). More...

static __inline__ 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). More...

static __inline__ 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. More...

static __inline__ void	_Chain_Iterator_registry_initialize (Chain_Iterator_registry *the_registry)
	Initializes a chain iterator registry. More...

static __inline__ 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. More...

static __inline__ 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. More...

static __inline__ Chain_Node *	_Chain_Iterator_next (const Chain_Iterator *the_iterator)
	Returns the next node in the iterator direction. More...

static __inline__ void	_Chain_Iterator_set_position (Chain_Iterator the_iterator, Chain_Node the_node)
	Sets the iterator position. More...

static __inline__ void	_Chain_Iterator_destroy (Chain_Iterator *the_iterator)
	Destroys the iterator. More...

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

Definition at line 47 of file chainimpl.h.

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

Definition at line 943 of file chainimpl.h.

◆ 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().

Definition at line 55 of file chainimpl.h.

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.

Definition at line 51 of file chain.h.

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

Definition at line 844 of file chainimpl.h.

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.

Definition at line 884 of file chainimpl.h.

Function Documentation

◆ _Chain_Append_if_is_off_chain_unprotected()

static __inline__ void _Chain_Append_if_is_off_chain_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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

Definition at line 711 of file chainimpl.h.

◆ _Chain_Append_unprotected()

static __inline__ void _Chain_Append_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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.

Definition at line 680 of file chainimpl.h.

◆ _Chain_Append_with_empty_check_unprotected()

static __inline__ bool _Chain_Append_with_empty_check_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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.

Definition at line 754 of file chainimpl.h.

◆ _Chain_Are_nodes_equal()

static __inline__ bool _Chain_Are_nodes_equal	(	const Chain_Node *	left,
		const Chain_Node *	right
	)

static

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.

Definition at line 161 of file chainimpl.h.

◆ _Chain_Extract_unprotected()

static __inline__ void _Chain_Extract_unprotected ( Chain_Node * the_node )

static

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.

Definition at line 558 of file chainimpl.h.

◆ _Chain_First()

static __inline__ Chain_Node* _Chain_First ( const Chain_Control * the_chain )

static

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.

Definition at line 260 of file chainimpl.h.

◆ _Chain_Get_first_unprotected()

static __inline__ Chain_Node* _Chain_Get_first_unprotected ( Chain_Control * the_chain )

static

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.

Definition at line 592 of file chainimpl.h.

◆ _Chain_Get_unprotected()

static __inline__ Chain_Node* _Chain_Get_unprotected ( Chain_Control * the_chain )

static

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.

Definition at line 630 of file chainimpl.h.

◆ _Chain_Get_with_empty_check_unprotected()

static __inline__ bool _Chain_Get_with_empty_check_unprotected	(	Chain_Control *	the_chain,
		Chain_Node **	the_node
	)

static

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.

Definition at line 810 of file chainimpl.h.

◆ _Chain_Has_only_one_node()

static __inline__ bool _Chain_Has_only_one_node ( const Chain_Control * the_chain )

static

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.

Definition at line 450 of file chainimpl.h.

◆ _Chain_Head()

static __inline__ Chain_Node* _Chain_Head ( Chain_Control * the_chain )

static

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.

Definition at line 195 of file chainimpl.h.

◆ _Chain_Immutable_first()

static __inline__ const Chain_Node* _Chain_Immutable_first ( const Chain_Control * the_chain )

static

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.

Definition at line 277 of file chainimpl.h.

◆ _Chain_Immutable_head()

static __inline__ const Chain_Node* _Chain_Immutable_head ( const Chain_Control * the_chain )

static

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.

Definition at line 211 of file chainimpl.h.

◆ _Chain_Immutable_last()

static __inline__ const Chain_Node* _Chain_Immutable_last ( const Chain_Control * the_chain )

static

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.

Definition at line 311 of file chainimpl.h.

◆ _Chain_Immutable_next()

static __inline__ const Chain_Node* _Chain_Immutable_next ( const Chain_Node * the_node )

static

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.

Definition at line 343 of file chainimpl.h.

◆ _Chain_Immutable_previous()

static __inline__ const Chain_Node* _Chain_Immutable_previous ( const Chain_Node * the_node )

static

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.

Definition at line 375 of file chainimpl.h.

◆ _Chain_Immutable_tail()

static __inline__ const Chain_Node* _Chain_Immutable_tail ( const Chain_Control * the_chain )

static

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.

Definition at line 243 of file chainimpl.h.

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

Definition at line 26 of file chain.c.

◆ _Chain_Initialize_empty()

static __inline__ void _Chain_Initialize_empty ( Chain_Control * the_chain )

static

Initializes this chain as empty.

This routine initializes the specified chain to contain zero nodes.

Parameters

[out] the_chain The chain to be initialized.

Definition at line 505 of file chainimpl.h.

◆ _Chain_Initialize_node()

static __inline__ void _Chain_Initialize_node ( Chain_Node * the_node )

static

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.

Definition at line 122 of file chainimpl.h.

◆ _Chain_Initialize_one()

static __inline__ void _Chain_Initialize_one	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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.

Definition at line 528 of file chainimpl.h.

◆ _Chain_Insert_ordered_unprotected()

static __inline__ void _Chain_Insert_ordered_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	to_insert,
		const void *	left,
		Chain_Node_order	order
	)

static

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.

Definition at line 864 of file chainimpl.h.

◆ _Chain_Insert_unprotected()

static __inline__ void _Chain_Insert_unprotected	(	Chain_Node *	after_node,
		Chain_Node *	the_node
	)

static

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.

Definition at line 653 of file chainimpl.h.

◆ _Chain_Is_empty()

static __inline__ bool _Chain_Is_empty ( const Chain_Control * the_chain )

static

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.

Definition at line 393 of file chainimpl.h.

◆ _Chain_Is_first()

static __inline__ bool _Chain_Is_first ( const Chain_Node * the_node )

static

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.

Definition at line 413 of file chainimpl.h.

◆ _Chain_Is_head()

static __inline__ bool _Chain_Is_head	(	const Chain_Control *	the_chain,
		const Chain_Node *	the_node
	)

static

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.

Definition at line 470 of file chainimpl.h.

◆ _Chain_Is_last()

static __inline__ bool _Chain_Is_last ( const Chain_Node * the_node )

static

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.

Definition at line 432 of file chainimpl.h.

◆ _Chain_Is_node_off_chain()

static __inline__ bool _Chain_Is_node_off_chain ( const Chain_Node * node )

static

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.

Definition at line 142 of file chainimpl.h.

◆ _Chain_Is_null_node()

static __inline__ bool _Chain_Is_null_node ( const Chain_Node * the_node )

static

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

Definition at line 179 of file chainimpl.h.

◆ _Chain_Is_tail()

static __inline__ bool _Chain_Is_tail	(	const Chain_Control *	the_chain,
		const Chain_Node *	the_node
	)

static

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.

Definition at line 490 of file chainimpl.h.

◆ _Chain_Iterator_destroy()

static __inline__ void _Chain_Iterator_destroy ( Chain_Iterator * the_iterator )

static

Destroys the iterator.

Removes the iterator from its registry.

Parameters

[out] the_iterator The chain iterator.

Definition at line 1121 of file chainimpl.h.

◆ _Chain_Iterator_initialize()

static __inline__ void _Chain_Iterator_initialize	(	Chain_Control *	the_chain,
		Chain_Iterator_registry *	the_registry,
		Chain_Iterator *	the_iterator,
		Chain_Iterator_direction	direction
	)

static

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 );
}

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

Definition at line 1057 of file chainimpl.h.

◆ _Chain_Iterator_next()

static __inline__ Chain_Node* _Chain_Iterator_next ( const Chain_Iterator * the_iterator )

static

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

Definition at line 1089 of file chainimpl.h.

◆ _Chain_Iterator_registry_initialize()

static __inline__ void _Chain_Iterator_registry_initialize ( Chain_Iterator_registry * the_registry )

static

Initializes a chain iterator registry.

Parameters

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

Definition at line 951 of file chainimpl.h.

◆ _Chain_Iterator_registry_update()

static __inline__ void _Chain_Iterator_registry_update	(	Chain_Iterator_registry *	the_registry,
		Chain_Node *	the_node_to_extract
	)

static

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.

Definition at line 970 of file chainimpl.h.

◆ _Chain_Iterator_set_position()

static __inline__ void _Chain_Iterator_set_position	(	Chain_Iterator *	the_iterator,
		Chain_Node *	the_node
	)

static

Sets the iterator position.

Parameters

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

Definition at line 1106 of file chainimpl.h.

◆ _Chain_Last()

static __inline__ Chain_Node* _Chain_Last ( const Chain_Control * the_chain )

static

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.

Definition at line 294 of file chainimpl.h.

◆ _Chain_Next()

static __inline__ Chain_Node* _Chain_Next ( const Chain_Node * the_node )

static

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.

Definition at line 327 of file chainimpl.h.

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

Definition at line 21 of file chainnodecount.c.

◆ _Chain_Prepend_unprotected()

static __inline__ void _Chain_Prepend_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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.

Definition at line 732 of file chainimpl.h.

◆ _Chain_Prepend_with_empty_check_unprotected()

static __inline__ bool _Chain_Prepend_with_empty_check_unprotected	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

static

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.

Definition at line 780 of file chainimpl.h.

◆ _Chain_Previous()

static __inline__ Chain_Node* _Chain_Previous ( const Chain_Node * the_node )

static

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.

Definition at line 359 of file chainimpl.h.

◆ _Chain_Set_off_chain()

static __inline__ void _Chain_Set_off_chain ( Chain_Node * node )

static

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.

Definition at line 104 of file chainimpl.h.

◆ _Chain_Tail()

static __inline__ Chain_Node* _Chain_Tail ( Chain_Control * the_chain )

static

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.

Definition at line 227 of file chainimpl.h.

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CHAIN_INITIALIZER_ONE_NODE

◆ CHAIN_ITERATOR_REGISTRY_INITIALIZER

◆ CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN

Typedef Documentation

◆ Chain_Node

◆ Chain_Node_order

Enumeration Type Documentation

◆ Chain_Iterator_direction

Function Documentation

◆ _Chain_Append_if_is_off_chain_unprotected()

◆ _Chain_Append_unprotected()

◆ _Chain_Append_with_empty_check_unprotected()

◆ _Chain_Are_nodes_equal()

◆ _Chain_Extract_unprotected()

◆ _Chain_First()

◆ _Chain_Get_first_unprotected()

◆ _Chain_Get_unprotected()

◆ _Chain_Get_with_empty_check_unprotected()

◆ _Chain_Has_only_one_node()

◆ _Chain_Head()

◆ _Chain_Immutable_first()

◆ _Chain_Immutable_head()

◆ _Chain_Immutable_last()

◆ _Chain_Immutable_next()

◆ _Chain_Immutable_previous()

◆ _Chain_Immutable_tail()

◆ _Chain_Initialize()

◆ _Chain_Initialize_empty()

◆ _Chain_Initialize_node()

◆ _Chain_Initialize_one()

◆ _Chain_Insert_ordered_unprotected()

◆ _Chain_Insert_unprotected()

◆ _Chain_Is_empty()

◆ _Chain_Is_first()

◆ _Chain_Is_head()

◆ _Chain_Is_last()

◆ _Chain_Is_node_off_chain()

◆ _Chain_Is_null_node()

◆ _Chain_Is_tail()

◆ _Chain_Iterator_destroy()

◆ _Chain_Iterator_initialize()

◆ _Chain_Iterator_next()

◆ _Chain_Iterator_registry_initialize()

◆ _Chain_Iterator_registry_update()

◆ _Chain_Iterator_set_position()

◆ _Chain_Last()

◆ _Chain_Next()

◆ _Chain_Node_count_unprotected()

◆ _Chain_Prepend_unprotected()

◆ _Chain_Prepend_with_empty_check_unprotected()

◆ _Chain_Previous()

◆ _Chain_Set_off_chain()

◆ _Chain_Tail()