Chain Handler


Data Structures
struct	Chain_Node_struct
struct	Chain_Control
Typedefs
typedef struct Chain_Node_struct	Chain_Node
Functions
void	_Chain_Initialize (Chain_Control the_chain, void starting_address, size_t number_nodes, size_t node_size)
	Initialize a Chain Header.
void	_Chain_Extract (Chain_Node *the_node)
	Extract the specified node from a chain.
Chain_Node *	_Chain_Get (Chain_Control *the_chain)
	Obtain the first node on a chain.
void	_Chain_Insert (Chain_Node after_node, Chain_Node the_node)
	Insert a node on a chain.
void	_Chain_Append (Chain_Control the_chain, Chain_Node the_node)
	Append a node on the end of a chain.
RTEMS_INLINE_ROUTINE boolean	_Chain_Are_nodes_equal (const Chain_Node left, const Chain_Node right)
	Are Two Nodes Equal.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_null (const Chain_Control *the_chain)
	Is this Chain Control Pointer Null.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_null_node (const Chain_Node *the_node)
	Is the Chain Node Pointer NULL.
RTEMS_INLINE_ROUTINE Chain_Node *	_Chain_Head (Chain_Control *the_chain)
	Return pointer to Chain Head.
RTEMS_INLINE_ROUTINE Chain_Node *	_Chain_Tail (Chain_Control *the_chain)
	Return pointer to Chain Tail.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_empty (Chain_Control *the_chain)
	Is the Chain Empty.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_first (const Chain_Node *the_node)
	Is this the First Node on the Chain.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_last (const Chain_Node *the_node)
	Is this the Last Node on the Chain.
RTEMS_INLINE_ROUTINE boolean	_Chain_Has_only_one_node (const Chain_Control *the_chain)
	Does this Chain have only One Node.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_head (Chain_Control the_chain, const Chain_Node the_node)
	Is this Node the Chain Head.
RTEMS_INLINE_ROUTINE boolean	_Chain_Is_tail (Chain_Control the_chain, const Chain_Node the_node)
	Is this Node the Chail Tail.
RTEMS_INLINE_ROUTINE void	_Chain_Initialize_empty (Chain_Control *the_chain)
	Initialize this Chain as Empty.
RTEMS_INLINE_ROUTINE void	_Chain_Extract_unprotected (Chain_Node *the_node)
	Extract this Node (unprotected).
RTEMS_INLINE_ROUTINE Chain_Node *	_Chain_Get_first_unprotected (Chain_Control *the_chain)
	Get the First Node (unprotected).
RTEMS_INLINE_ROUTINE Chain_Node *	_Chain_Get_unprotected (Chain_Control *the_chain)
	Get the First Node (unprotected).
RTEMS_INLINE_ROUTINE void	_Chain_Insert_unprotected (Chain_Node after_node, Chain_Node the_node)
	Insert a Node (unprotected).
RTEMS_INLINE_ROUTINE void	_Chain_Append_unprotected (Chain_Control the_chain, Chain_Node the_node)
	Append a Node (unprotected).
RTEMS_INLINE_ROUTINE void	_Chain_Prepend_unprotected (Chain_Control the_chain, Chain_Node the_node)
	Prepend a Node (unprotected).
RTEMS_INLINE_ROUTINE void	_Chain_Prepend (Chain_Control the_chain, Chain_Node the_node)
	Prepend a Node (protected).

Detailed Description

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.

Typedef Documentation

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.

Function Documentation

void _Chain_Append	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

Append a node on the end of a chain.

This routine appends the_node onto the end of the_chain.

Note:: It disables interrupts to ensure the atomicity of the append operation.

Referenced by _CORE_message_queue_Free_message_buffer(), _Objects_MP_Free_global_object(), and _Thread_MP_Free_proxy().

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

Append a Node (unprotected).

This routine appends the_node onto the end of the_chain.

Parameters:

`[in]`	the_chain	is the chain to be operated upon.
`[in]`	the_node	is the node to be appended.

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

References _Chain_Tail(), Chain_Control::last, Chain_Node_struct::next, and Chain_Node_struct::previous.

Referenced by _CORE_message_queue_Append_unprotected().

RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal	(	const Chain_Node *	left,
		const Chain_Node *	right
	)

Are Two Nodes Equal.

This function returns TRUE if left and right are equal, and FALSE otherwise.

Parameters:

`[in]`	left	is the node on the left hand side of the comparison.
`[in]`	right	is the node on the left hand side of the comparison.

Returns:: This function returns TRUE if left and right are equal, and FALSE otherwise.

void _Chain_Extract ( Chain_Node * the_node )

Extract the specified node from a chain.

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

the_node specifies the node to extract

Referenced by _Thread_MP_Free_proxy().

RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected ( Chain_Node * the_node )

Extract 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:

[in] the_node is the node to be extracted.

References Chain_Node_struct::next, and Chain_Node_struct::previous.

Chain_Node* _Chain_Get ( Chain_Control * the_chain )

Obtain the first node on a chain.

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.

Returns:: This method returns a pointer a node. If a node was removed, then a pointer to that node is returned. If the_chain was empty, then NULL is returned.

Note:: It disables interrupts to ensure the atomicity of the get operation.

Referenced by _CORE_message_queue_Allocate_message_buffer(), and _Objects_MP_Allocate_global_object().

RTEMS_INLINE_ROUTINE Chain_Node* _Chain_Get_first_unprotected ( Chain_Control * the_chain )

Get 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] the_chain is 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.

References _Chain_Head(), Chain_Control::first, Chain_Node_struct::next, and Chain_Node_struct::previous.

Referenced by _Chain_Get_unprotected().

RTEMS_INLINE_ROUTINE Chain_Node* _Chain_Get_unprotected ( Chain_Control * the_chain )

Get 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] the_chain is the chain to attempt to get the first node from.

Returns:: This method returns 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.

References _Chain_Get_first_unprotected(), and _Chain_Is_empty().

Referenced by _CORE_message_queue_Get_pending_message().

RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node ( const Chain_Control * the_chain )

Does this Chain have only One Node.

This function returns TRUE if there is only one node on the_chain and FALSE otherwise.

Parameters:

[in] the_chain is the chain to be operated upon.

Returns:: This function returns TRUE if there is only one node on the_chain and FALSE otherwise.

References Chain_Control::first, and Chain_Control::last.

RTEMS_INLINE_ROUTINE Chain_Node* _Chain_Head ( Chain_Control * the_chain )

Return pointer to Chain Head.

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

Parameters:

[in] the_chain is the chain to be operated upon.

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

Referenced by _Chain_Get_first_unprotected(), _Chain_Initialize_empty(), _Chain_Is_head(), _Chain_Prepend(), and _Chain_Prepend_unprotected().

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

Initialize 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:

`[in]`	the_chain	specifies the chain to initialize
`[in]`	starting_address	is the starting address of the array of elements
`[in]`	number_nodes	is the numebr of nodes that will be in the chain
`[in]`	node_size	is the size of each node

RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty ( Chain_Control * the_chain )

Initialize this Chain as Empty.

This routine initializes the specified chain to contain zero nodes.

Parameters:

[in] the_chain is the chain to be initialized.

References _Chain_Head(), _Chain_Tail(), Chain_Control::first, Chain_Control::last, and Chain_Control::permanent_null.

void _Chain_Insert	(	Chain_Node *	after_node,
		Chain_Node *	the_node
	)

Insert a node on a chain.

This routine inserts the_node on a chain immediately following after_node.

Note:: It disables interrupts to ensure the atomicity of the extract operation.

Referenced by _Chain_Prepend().

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

Insert a Node (unprotected).

This routine inserts the_node on a chain immediately following after_node.

Parameters:

`[in]`	after_node	is the node which will precede the_node on the chain.
`[in]`	the_node	is the node to be inserted.

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

References Chain_Node_struct::next, and Chain_Node_struct::previous.

Referenced by _Chain_Prepend_unprotected().

RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty ( Chain_Control * the_chain )

Is the Chain Empty.

This function returns TRUE if there a no nodes on the_chain and FALSE otherwise.

Parameters:

[in] the_chain is the chain to be operated upon.

Returns:: This function returns TRUE if there a no nodes on the_chain and FALSE otherwise.

References _Chain_Tail(), and Chain_Control::first.

Referenced by _Chain_Get_unprotected().

RTEMS_INLINE_ROUTINE boolean _Chain_Is_first ( const Chain_Node * the_node )

Is this the First Node on the Chain.

This function returns TRUE if the_node is the first node on a chain and FALSE otherwise.

Parameters:

[in] the_node is the node the caller wants to know if it is the first node on a chain.

Returns:: This function returns TRUE if the_node is the first node on a chain and FALSE otherwise.

References Chain_Node_struct::previous.

RTEMS_INLINE_ROUTINE boolean _Chain_Is_head	(	Chain_Control *	the_chain,
		const Chain_Node *	the_node
	)

Is this Node the Chain Head.

This function returns TRUE if the_node is the head of the_chain and FALSE otherwise.

Parameters:

`[in]`	the_chain	is the chain to be operated upon.
`[in]`	the_node	is the node to check for being the Chain Head.

Returns:: This function returns TRUE if the_node is the head of the_chain and FALSE otherwise.

References _Chain_Head().

RTEMS_INLINE_ROUTINE boolean _Chain_Is_last ( const Chain_Node * the_node )

Is this the Last Node on the Chain.

This function returns TRUE if the_node is the last node on a chain and FALSE otherwise.

Parameters:

[in] the_node is the node to check as the last node.

Returns:: This function returns TRUE if the_node is the last node on a chain and FALSE otherwise.

References Chain_Node_struct::next.

RTEMS_INLINE_ROUTINE boolean _Chain_Is_null ( const Chain_Control * the_chain )

Is this Chain Control Pointer Null.

This function returns TRUE if the_chain is NULL and FALSE otherwise.

Parameters:

[in] the_chain is the chain to be checked for empty status.

Returns:: This method returns TRUE if the_chain is NULL and FALSE otherwise.

RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node ( const Chain_Node * the_node )

Is the Chain Node Pointer NULL.

This function returns TRUE if the_node is NULL and FALSE otherwise.

Parameters:

[in] the_node is the node pointer to check.

Returns:: This method returns TRUE if the_node is NULL and FALSE otherwise.

RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail	(	Chain_Control *	the_chain,
		const Chain_Node *	the_node
	)

Is this Node the Chail Tail.

This function returns TRUE if the_node is the tail of the_chain and FALSE otherwise.

Parameters:

`[in]`	the_chain	is the chain to be operated upon.
`[in]`	the_node	is the node to check for being the Chain Tail.

References _Chain_Tail().

RTEMS_INLINE_ROUTINE void _Chain_Prepend	(	Chain_Control *	the_chain,
		Chain_Node *	the_node
	)

Prepend a Node (protected).

This routine prepends the_node onto the front of the_chain.

Parameters:

`[in]`	the_chain	is the chain to be operated upon.
`[in]`	the_node	is the node to be prepended.

Note:: It disables interrupts to ensure the atomicity of the prepend operation.

References _Chain_Head(), and _Chain_Insert().

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

Prepend a Node (unprotected).

This routine prepends the_node onto the front of the_chain.

Parameters:

`[in]`	the_chain	is the chain to be operated upon.
`[in]`	the_node	is the node to be prepended.

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

References _Chain_Head(), and _Chain_Insert_unprotected().

Referenced by _CORE_message_queue_Prepend_unprotected(), and _CORE_mutex_Seize_interrupt_trylock_body().

RTEMS_INLINE_ROUTINE Chain_Node* _Chain_Tail ( Chain_Control * the_chain )

Return pointer to Chain Tail.

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

Parameters:

[in] the_chain is the chain to be operated upon.

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

References Chain_Control::permanent_null.

Referenced by _Chain_Append_unprotected(), _Chain_Initialize_empty(), _Chain_Is_empty(), and _Chain_Is_tail().

Chain Handler

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation