Chain API. More...

Collaboration diagram for Chains:

Defines
#define	RTEMS_CHAIN_INITIALIZER_EMPTY(name) CHAIN_INITIALIZER_EMPTY(name)
	Chain initializer for an empty chain with designator name.
#define	RTEMS_CHAIN_DEFINE_EMPTY(name) CHAIN_DEFINE_EMPTY(name)
	Chain definition for an empty chain with designator name.
Typedefs
typedef Chain_Node	rtems_chain_node
typedef Chain_Control	rtems_chain_control
Functions
rtems_status_code	rtems_chain_append_with_notification (rtems_chain_control chain, rtems_chain_node node, rtems_id task, rtems_event_set events)
	Appends the node to the chain and sends the events to the task if the chain was empty before the append.
rtems_status_code	rtems_chain_prepend_with_notification (rtems_chain_control chain, rtems_chain_node node, rtems_id task, rtems_event_set events)
	Prepends the node to the chain and sends the events to the task if the chain was empty before the prepend.
rtems_status_code	rtems_chain_get_with_notification (rtems_chain_control chain, rtems_id task, rtems_event_set events, rtems_chain_node *node)
	Gets the first node of the chain and sends the events to the task if the chain is empty after the get.
rtems_status_code	rtems_chain_get_with_wait (rtems_chain_control chain, rtems_event_set events, rtems_interval timeout, rtems_chain_node *node)
	Gets the first node of the chain and sends the events to the task if the chain is empty afterwards.
RTEMS_INLINE_ROUTINE void	rtems_chain_initialize (rtems_chain_control the_chain, void starting_address, size_t number_nodes, size_t node_size)
	Initialize a chain Header.
RTEMS_INLINE_ROUTINE void	rtems_chain_initialize_empty (rtems_chain_control *the_chain)
	Initialize this chain as empty.
RTEMS_INLINE_ROUTINE void	rtems_chain_set_off_chain (rtems_chain_node *node)
	Set off chain.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_node_off_chain (const rtems_chain_node *node)
	Is the node off chain.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_null_node (const rtems_chain_node *the_node)
	Is the chain node pointer NULL.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_head (rtems_chain_control *the_chain)
	Return pointer to Chain Head.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_head (const rtems_chain_control *the_chain)
	Return pointer to immutable Chain Head.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_tail (rtems_chain_control *the_chain)
	Return pointer to Chain Tail.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_tail (const rtems_chain_control *the_chain)
	Return pointer to immutable Chain Tail.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_first (rtems_chain_control *the_chain)
	Return pointer to Chain's First node after the permanent head.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_first (const rtems_chain_control *the_chain)
	Return pointer to immutable Chain's First node.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_last (rtems_chain_control *the_chain)
	Return pointer to Chain's Last node before the permanent tail.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_last (const rtems_chain_control *the_chain)
	Return pointer to immutable Chain's Last node.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_next (rtems_chain_node *the_node)
	Return pointer the next node from this node.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_next (const rtems_chain_node *the_node)
	Return pointer the immutable next node from this node.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_previous (rtems_chain_node *the_node)
	Return pointer the previous node from this node.
RTEMS_INLINE_ROUTINE const rtems_chain_node *	rtems_chain_immutable_previous (const rtems_chain_node *the_node)
	Return pointer the immutable previous node from this node.
RTEMS_INLINE_ROUTINE bool	rtems_chain_are_nodes_equal (const rtems_chain_node left, const rtems_chain_node right)
	Are Two nodes equal.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_empty (const rtems_chain_control *the_chain)
	Is the chain empty.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_first (const rtems_chain_node *the_node)
	Is this the first node on the chain.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_last (const rtems_chain_node *the_node)
	Is this the last node on the chain.
RTEMS_INLINE_ROUTINE bool	rtems_chain_has_only_one_node (const rtems_chain_control *the_chain)
	Does this chain have only one node.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_head (const rtems_chain_control the_chain, const rtems_chain_node the_node)
	Is this node the chain head.
RTEMS_INLINE_ROUTINE bool	rtems_chain_is_tail (const rtems_chain_control the_chain, const rtems_chain_node the_node)
	Is this node the chain tail.
RTEMS_INLINE_ROUTINE void	rtems_chain_extract (rtems_chain_node *the_node)
	Extract the specified node from a chain.
RTEMS_INLINE_ROUTINE void	rtems_chain_extract_unprotected (rtems_chain_node *the_node)
	Extract the specified node from a chain (unprotected).
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_get (rtems_chain_control *the_chain)
	Obtain the first node on a chain.
RTEMS_INLINE_ROUTINE rtems_chain_node *	rtems_chain_get_unprotected (rtems_chain_control *the_chain)
	See _Chain_Get_unprotected().
RTEMS_INLINE_ROUTINE void	rtems_chain_insert (rtems_chain_node after_node, rtems_chain_node the_node)
	Insert a node on a chain.
RTEMS_INLINE_ROUTINE void	rtems_chain_insert_unprotected (rtems_chain_node after_node, rtems_chain_node the_node)
	See _Chain_Insert_unprotected().
RTEMS_INLINE_ROUTINE void	rtems_chain_append (rtems_chain_control the_chain, rtems_chain_node the_node)
	Append a node on the end of a chain.
RTEMS_INLINE_ROUTINE void	rtems_chain_append_unprotected (rtems_chain_control the_chain, rtems_chain_node the_node)
	Append a node on the end of a chain (unprotected).
RTEMS_INLINE_ROUTINE void	rtems_chain_prepend (rtems_chain_control the_chain, rtems_chain_node the_node)
	Prepend a node.
RTEMS_INLINE_ROUTINE void	rtems_chain_prepend_unprotected (rtems_chain_control the_chain, rtems_chain_node the_node)
	Prepend a node (unprotected).
RTEMS_INLINE_ROUTINE bool	rtems_chain_append_with_empty_check (rtems_chain_control chain, rtems_chain_node node)
	Checks if the chain is empty and appends the node.
RTEMS_INLINE_ROUTINE bool	rtems_chain_prepend_with_empty_check (rtems_chain_control chain, rtems_chain_node node)
	Checks if the chain is empty and prepends the node.
RTEMS_INLINE_ROUTINE bool	rtems_chain_get_with_empty_check (rtems_chain_control chain, rtems_chain_node *node)
	Tries to get the first node and check if the chain is empty afterwards.
RTEMS_INLINE_ROUTINE size_t	rtems_chain_node_count_unprotected (const rtems_chain_control *chain)
	Returns the node count of the chain.

Detailed Description

Chain API.

Function Documentation

RTEMS_INLINE_ROUTINE void rtems_chain_append	(	rtems_chain_control *	the_chain,
		rtems_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.

References _Chain_Append().

RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected	(	rtems_chain_control *	the_chain,
		rtems_chain_node *	the_node
	)

Append a node on the end of a chain (unprotected).

This routine appends the_node onto the end of the_chain.

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

References _Chain_Append_unprotected().

RTEMS_INLINE_ROUTINE bool rtems_chain_append_with_empty_check	(	rtems_chain_control *	chain,
		rtems_chain_node *	node
	)

Checks if the chain is empty and appends the node.

Interrupts are disabled to ensure the atomicity of the operation.

Return values:

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

References _Chain_Append_with_empty_check().

rtems_status_code rtems_chain_append_with_notification	(	rtems_chain_control *	chain,
		rtems_chain_node *	node,
		rtems_id	task,
		rtems_event_set	events
	)

Appends the node to the chain and sends the events to the task if the chain was empty before the append.

See also:: rtems_chain_append_with_empty_check() and rtems_event_send().

Return values:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	No such task.

RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal	(	const rtems_chain_node *	left,
		const rtems_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.

Return values:

true	left is equal to right.
false	left is not equal to right

References _Chain_Are_nodes_equal().

RTEMS_INLINE_ROUTINE void rtems_chain_extract ( rtems_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

References _Chain_Extract().

RTEMS_INLINE_ROUTINE void rtems_chain_extract_unprotected ( rtems_chain_node * the_node )

Extract the specified node from a chain (unprotected).

This routine extracts the_node from the chain on which it resides.

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

References _Chain_Extract_unprotected().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_first ( rtems_chain_control * the_chain )

Return pointer to Chain's First node after the permanent head.

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

Parameters:

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

Returns:: This method returns the first node of the chain.

References _Chain_First().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_get ( rtems_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.

References _Chain_Get().

RTEMS_INLINE_ROUTINE bool rtems_chain_get_with_empty_check	(	rtems_chain_control *	chain,
		rtems_chain_node **	node
	)

Tries to get the first node and check if the chain is empty afterwards.

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

Interrupts are disabled to ensure the atomicity of the operation.

Return values:

true	The chain is empty after the node removal.
false	The chain contained at least one node after the node removal.

References _Chain_Get_with_empty_check().

rtems_status_code rtems_chain_get_with_notification	(	rtems_chain_control *	chain,
		rtems_id	task,
		rtems_event_set	events,
		rtems_chain_node **	node
	)

Gets the first node of the chain and sends the events to the task if the chain is empty after the get.

See also:: rtems_chain_get_with_empty_check() and rtems_event_send().

Return values:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	No such task.

rtems_status_code rtems_chain_get_with_wait	(	rtems_chain_control *	chain,
		rtems_event_set	events,
		rtems_interval	timeout,
		rtems_chain_node **	node
	)

Gets the first node of the chain and sends the events to the task if the chain is empty afterwards.

See also:: rtems_chain_get() and rtems_event_receive().

Return values:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_TIMEOUT	Timeout.

RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node ( const rtems_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.

Return values:

true	The chain has only one node.
false	The chain has more than one nodes.

References _Chain_Has_only_one_node().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_head ( rtems_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 node of the chain.

References _Chain_Head().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_first ( const rtems_chain_control * the_chain )

Return pointer to immutable Chain's First node.

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

Parameters:

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

Returns:: This method returns the first node of the chain.

References _Chain_Immutable_first().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_head ( const rtems_chain_control * the_chain )

Return pointer to immutable Chain Head.

This function returns a pointer to the head 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.

References _Chain_Immutable_head().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_last ( const rtems_chain_control * the_chain )

Return pointer to immutable Chain's Last node.

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

Parameters:

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

Returns:: This method returns the last node of the chain.

References _Chain_Immutable_last().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_next ( const rtems_chain_node * the_node )

Return pointer the immutable next node from this node.

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

Parameters:

[in] the_node is the node to be operated upon.

Returns:: This method returns the next node on the chain.

References _Chain_Immutable_next().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_previous ( const rtems_chain_node * the_node )

Return pointer the immutable previous node from this node.

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

Parameters:

[in] the_node is the node to be operated upon.

Returns:: This method returns the previous node on the chain.

References _Chain_Immutable_previous().

RTEMS_INLINE_ROUTINE const rtems_chain_node* rtems_chain_immutable_tail ( const rtems_chain_control * the_chain )

Return pointer to immutable Chain Tail.

This function returns a pointer to the tail 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_Immutable_tail().

RTEMS_INLINE_ROUTINE void rtems_chain_initialize	(	rtems_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 number of nodes that will be in the chain
[in]	node_size	is the size of each node

References _Chain_Initialize().

RTEMS_INLINE_ROUTINE void rtems_chain_initialize_empty ( rtems_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_Initialize_empty().

RTEMS_INLINE_ROUTINE void rtems_chain_insert	(	rtems_chain_node *	after_node,
		rtems_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.

References _Chain_Insert().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty ( const rtems_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.

Return values:

true	The chain is empty.
false	The chain is not empty.

References _Chain_Is_empty().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_first ( const rtems_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.

Return values:

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

References _Chain_Is_first().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_head	(	const rtems_chain_control *	the_chain,
		const rtems_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.

Return values:

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

References _Chain_Is_head().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_last ( const rtems_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.

Return values:

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

References _Chain_Is_last().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_node_off_chain ( const rtems_chain_node * node )

Is the node off chain.

This function returns true if the node is not on a chain. A node is off chain if the next and previous fields are set to NULL.

Parameters:

[in] node is the node off chain.

Return values:

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

References _Chain_Is_node_off_chain().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node ( const rtems_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.

Return values:

true	The chain node pointer is NULL.
false	The chain node pointer is not NULL.

References _Chain_Is_null_node().

RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail	(	const rtems_chain_control *	the_chain,
		const rtems_chain_node *	the_node
	)

Is this node the chain 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.

Return values:

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

References _Chain_Is_tail().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_last ( rtems_chain_control * the_chain )

Return pointer to Chain's Last node before the permanent tail.

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

Parameters:

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

Returns:: This method returns the last node of the chain.

References _Chain_Last().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_next ( rtems_chain_node * the_node )

Return pointer the next node from this node.

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

Parameters:

[in] the_node is the node to be operated upon.

Returns:: This method returns the next node on the chain.

References _Chain_Next().

RTEMS_INLINE_ROUTINE size_t rtems_chain_node_count_unprotected ( const rtems_chain_control * chain )

Returns the node count of the chain.

Parameters:

[in] chain The chain.

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

Returns:: The node count of the chain.

References _Chain_Node_count_unprotected().

RTEMS_INLINE_ROUTINE void rtems_chain_prepend	(	rtems_chain_control *	the_chain,
		rtems_chain_node *	the_node
	)

Prepend a node.

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

RTEMS_INLINE_ROUTINE void rtems_chain_prepend_unprotected	(	rtems_chain_control *	the_chain,
		rtems_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_Prepend_unprotected().

RTEMS_INLINE_ROUTINE bool rtems_chain_prepend_with_empty_check	(	rtems_chain_control *	chain,
		rtems_chain_node *	node
	)

Checks if the chain is empty and prepends the node.

Interrupts are disabled to ensure the atomicity of the operation.

Return values:

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

References _Chain_Prepend_with_empty_check().

rtems_status_code rtems_chain_prepend_with_notification	(	rtems_chain_control *	chain,
		rtems_chain_node *	node,
		rtems_id	task,
		rtems_event_set	events
	)

Prepends the node to the chain and sends the events to the task if the chain was empty before the prepend.

See also:: rtems_chain_prepend_with_empty_check() and rtems_event_send().

Return values:

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	No such task.

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_previous ( rtems_chain_node * the_node )

Return pointer the previous node from this node.

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

Parameters:

[in] the_node is the node to be operated upon.

Returns:: This method returns the previous node on the chain.

References _Chain_Previous().

RTEMS_INLINE_ROUTINE void rtems_chain_set_off_chain ( rtems_chain_node * node )

Set off chain.

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

Parameters:

[in] node the node set to off chain.

References _Chain_Set_off_chain().

RTEMS_INLINE_ROUTINE rtems_chain_node* rtems_chain_tail ( rtems_chain_control * the_chain )

Return pointer to Chain Tail.

This function returns a pointer to the tail 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_Tail().

Defines

Typedefs

Functions

Detailed Description

Function Documentation