RTEMS
Macros | Typedefs | Functions
Chains

Chain API. More...

Macros

#define RTEMS_CHAIN_INITIALIZER_EMPTY(name)   CHAIN_INITIALIZER_EMPTY( name )
 Chain initializer for an empty chain with designator name.
 
#define RTEMS_CHAIN_INITIALIZER_ONE_NODE(node)   CHAIN_INITIALIZER_ONE_NODE( node )
 Chain initializer for a chain with one node. More...
 
#define RTEMS_CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN(chain)   CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN( chain )
 Chain node initializer for a chain containing exactly this node. More...
 
#define RTEMS_CHAIN_DEFINE_EMPTY(name)   rtems_chain_control name = RTEMS_CHAIN_INITIALIZER_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. More...
 
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. More...
 
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. More...
 
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. More...
 
static __inline__ void rtems_chain_initialize (rtems_chain_control *the_chain, void *starting_address, size_t number_nodes, size_t node_size)
 Initialize a chain Header. More...
 
static __inline__ void rtems_chain_initialize_empty (rtems_chain_control *the_chain)
 Initialize this chain as empty. More...
 
static __inline__ void rtems_chain_set_off_chain (rtems_chain_node *node)
 Set off chain. More...
 
static __inline__ void rtems_chain_initialize_node (rtems_chain_node *node)
 Initializes a chain node. More...
 
static __inline__ bool rtems_chain_is_node_off_chain (const rtems_chain_node *node)
 Is the node off chain. More...
 
static __inline__ bool rtems_chain_is_null_node (const rtems_chain_node *the_node)
 Is the chain node pointer NULL. More...
 
static __inline__ rtems_chain_nodertems_chain_head (rtems_chain_control *the_chain)
 Return pointer to Chain Head. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_head (const rtems_chain_control *the_chain)
 Return pointer to immutable Chain Head. More...
 
static __inline__ rtems_chain_nodertems_chain_tail (rtems_chain_control *the_chain)
 Return pointer to Chain Tail. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_tail (const rtems_chain_control *the_chain)
 Return pointer to immutable Chain Tail. More...
 
static __inline__ rtems_chain_nodertems_chain_first (const rtems_chain_control *the_chain)
 Return pointer to Chain's First node after the permanent head. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_first (const rtems_chain_control *the_chain)
 Return pointer to immutable Chain's First node. More...
 
static __inline__ rtems_chain_nodertems_chain_last (const rtems_chain_control *the_chain)
 Return pointer to Chain's Last node before the permanent tail. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_last (const rtems_chain_control *the_chain)
 Return pointer to immutable Chain's Last node. More...
 
static __inline__ rtems_chain_nodertems_chain_next (const rtems_chain_node *the_node)
 Return pointer the next node from this node. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_next (const rtems_chain_node *the_node)
 Return pointer the immutable next node from this node. More...
 
static __inline__ rtems_chain_nodertems_chain_previous (const rtems_chain_node *the_node)
 Return pointer the previous node from this node. More...
 
static __inline__ const rtems_chain_nodertems_chain_immutable_previous (const rtems_chain_node *the_node)
 Return pointer the immutable previous node from this node. More...
 
static __inline__ bool rtems_chain_are_nodes_equal (const rtems_chain_node *left, const rtems_chain_node *right)
 Are Two nodes equal. More...
 
static __inline__ bool rtems_chain_is_empty (const rtems_chain_control *the_chain)
 Is the chain empty. More...
 
static __inline__ bool rtems_chain_is_first (const rtems_chain_node *the_node)
 Is this the first node on the chain. More...
 
static __inline__ bool rtems_chain_is_last (const rtems_chain_node *the_node)
 Is this the last node on the chain. More...
 
static __inline__ bool rtems_chain_has_only_one_node (const rtems_chain_control *the_chain)
 Does this chain have only one node. More...
 
static __inline__ bool rtems_chain_is_head (const rtems_chain_control *the_chain, const rtems_chain_node *the_node)
 Is this node the chain head. More...
 
static __inline__ bool rtems_chain_is_tail (const rtems_chain_control *the_chain, const rtems_chain_node *the_node)
 Is this node the chain tail. More...
 
void rtems_chain_extract (rtems_chain_node *the_node)
 Extract the specified node from a chain. More...
 
static __inline__ void rtems_chain_extract_unprotected (rtems_chain_node *the_node)
 Extract the specified node from a chain (unprotected). More...
 
rtems_chain_nodertems_chain_get (rtems_chain_control *the_chain)
 Obtain the first node on a chain. More...
 
static __inline__ rtems_chain_nodertems_chain_get_unprotected (rtems_chain_control *the_chain)
 See _Chain_Get_unprotected().
 
static __inline__ rtems_chain_nodertems_chain_get_first_unprotected (rtems_chain_control *the_chain)
 See _Chain_Get_first_unprotected().
 
void rtems_chain_insert (rtems_chain_node *after_node, rtems_chain_node *the_node)
 Insert a node on a chain. More...
 
static __inline__ void rtems_chain_insert_unprotected (rtems_chain_node *after_node, rtems_chain_node *the_node)
 See _Chain_Insert_unprotected().
 
void rtems_chain_append (rtems_chain_control *the_chain, rtems_chain_node *the_node)
 Append a node on the end of a chain. More...
 
static __inline__ 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). More...
 
void rtems_chain_prepend (rtems_chain_control *the_chain, rtems_chain_node *the_node)
 Prepend a node. More...
 
static __inline__ void rtems_chain_prepend_unprotected (rtems_chain_control *the_chain, rtems_chain_node *the_node)
 Prepend a node (unprotected). More...
 
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. More...
 
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. More...
 
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. More...
 
static __inline__ size_t rtems_chain_node_count_unprotected (const rtems_chain_control *chain)
 Returns the node count of the chain. More...
 

Detailed Description

Chain API.

Macro Definition Documentation

◆ RTEMS_CHAIN_INITIALIZER_ONE_NODE

#define RTEMS_CHAIN_INITIALIZER_ONE_NODE (   node)    CHAIN_INITIALIZER_ONE_NODE( node )

Chain initializer for a chain with one node.

See also
RTEMS_CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN().

Definition at line 52 of file chain.h.

◆ RTEMS_CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN

#define RTEMS_CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN (   chain)    CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN( chain )

Chain node initializer for a chain containing exactly this node.

See also
RTEMS_CHAIN_INITIALIZER_ONE_NODE().

Definition at line 60 of file chain.h.

Function Documentation

◆ rtems_chain_append()

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.

◆ rtems_chain_append_unprotected()

static __inline__ void rtems_chain_append_unprotected ( rtems_chain_control the_chain,
rtems_chain_node the_node 
)
static

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.

Definition at line 679 of file chain.h.

◆ rtems_chain_append_with_empty_check()

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
trueThe chain was empty before the append.
falseThe chain contained at least one node before the append.

◆ rtems_chain_append_with_notification()

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_SUCCESSFULSuccessful operation.
RTEMS_INVALID_IDNo such task.

◆ rtems_chain_are_nodes_equal()

static __inline__ bool rtems_chain_are_nodes_equal ( const rtems_chain_node left,
const rtems_chain_node right 
)
static

Are Two nodes equal.

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

Parameters
[in]leftis the node on the left hand side of the comparison.
[in]rightis the node on the left hand side of the comparison.
Return values
trueleft is equal to right.
falseleft is not equal to right

Definition at line 448 of file chain.h.

◆ rtems_chain_extract()

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

◆ rtems_chain_extract_unprotected()

static __inline__ void rtems_chain_extract_unprotected ( rtems_chain_node the_node)
static

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.

Definition at line 590 of file chain.h.

◆ rtems_chain_first()

static __inline__ rtems_chain_node* rtems_chain_first ( const rtems_chain_control the_chain)
static

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_chainis the chain to be operated upon.
Returns
This method returns the first node of the chain.

Definition at line 314 of file chain.h.

◆ rtems_chain_get()

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.

◆ rtems_chain_get_with_empty_check()

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
trueThe chain is empty after the node removal.
falseThe chain contained at least one node after the node removal.

◆ rtems_chain_get_with_notification()

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_SUCCESSFULSuccessful operation.
RTEMS_INVALID_IDNo such task.

◆ rtems_chain_get_with_wait()

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_SUCCESSFULSuccessful operation.
RTEMS_TIMEOUTTimeout.

◆ rtems_chain_has_only_one_node()

static __inline__ bool rtems_chain_has_only_one_node ( const rtems_chain_control the_chain)
static

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_chainis the chain to be operated upon.
Return values
trueThe chain has only one node.
falseThe chain has more than one nodes.

Definition at line 522 of file chain.h.

◆ rtems_chain_head()

static __inline__ rtems_chain_node* rtems_chain_head ( rtems_chain_control the_chain)
static

Return pointer to Chain Head.

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

Parameters
[in]the_chainis the chain to be operated upon.
Returns
This method returns the permanent node of the chain.

Definition at line 249 of file chain.h.

◆ rtems_chain_immutable_first()

static __inline__ const rtems_chain_node* rtems_chain_immutable_first ( const rtems_chain_control the_chain)
static

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_chainis the chain to be operated upon.
Returns
This method returns the first node of the chain.

Definition at line 331 of file chain.h.

◆ rtems_chain_immutable_head()

static __inline__ const rtems_chain_node* rtems_chain_immutable_head ( const rtems_chain_control the_chain)
static

Return pointer to immutable Chain Head.

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

Parameters
[in]the_chainis the chain to be operated upon.
Returns
This method returns the permanent head node of the chain.

Definition at line 265 of file chain.h.

◆ rtems_chain_immutable_last()

static __inline__ const rtems_chain_node* rtems_chain_immutable_last ( const rtems_chain_control the_chain)
static

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_chainis the chain to be operated upon.
Returns
This method returns the last node of the chain.

Definition at line 365 of file chain.h.

◆ rtems_chain_immutable_next()

static __inline__ const rtems_chain_node* rtems_chain_immutable_next ( const rtems_chain_node the_node)
static

Return pointer the immutable next node from this node.

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

Parameters
[in]the_nodeis the node to be operated upon.
Returns
This method returns the next node on the chain.

Definition at line 397 of file chain.h.

◆ rtems_chain_immutable_previous()

static __inline__ const rtems_chain_node* rtems_chain_immutable_previous ( const rtems_chain_node the_node)
static

Return pointer the immutable previous node from this node.

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

Parameters
[in]the_nodeis the node to be operated upon.
Returns
This method returns the previous node on the chain.

Definition at line 429 of file chain.h.

◆ rtems_chain_immutable_tail()

static __inline__ const rtems_chain_node* rtems_chain_immutable_tail ( const rtems_chain_control the_chain)
static

Return pointer to immutable Chain Tail.

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

Parameters
[in]the_chainis the chain to be operated upon.
Returns
This method returns the permanent tail node of the chain.

Definition at line 297 of file chain.h.

◆ rtems_chain_initialize()

static __inline__ void rtems_chain_initialize ( rtems_chain_control the_chain,
void *  starting_address,
size_t  number_nodes,
size_t  node_size 
)
static

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_chainspecifies the chain to initialize
[in]starting_addressis the starting address of the array of elements
[in]number_nodesis the number of nodes that will be in the chain
[in]node_sizeis the size of each node

Definition at line 146 of file chain.h.

◆ rtems_chain_initialize_empty()

static __inline__ void rtems_chain_initialize_empty ( rtems_chain_control the_chain)
static

Initialize this chain as empty.

This routine initializes the specified chain to contain zero nodes.

Parameters
[in]the_chainis the chain to be initialized.

Definition at line 168 of file chain.h.

◆ rtems_chain_initialize_node()

static __inline__ void rtems_chain_initialize_node ( rtems_chain_node node)
static

Initializes a chain node.

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

Parameters
[in]the_nodeThe chain node to initialize.

Definition at line 198 of file chain.h.

◆ rtems_chain_insert()

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.

◆ rtems_chain_is_empty()

static __inline__ bool rtems_chain_is_empty ( const rtems_chain_control the_chain)
static

Is the chain empty.

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

Parameters
[in]the_chainis the chain to be operated upon.
Return values
trueThe chain is empty.
falseThe chain is not empty.

Definition at line 467 of file chain.h.

◆ rtems_chain_is_first()

static __inline__ bool rtems_chain_is_first ( const rtems_chain_node the_node)
static

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_nodeis the node the caller wants to know if it is the first node on a chain.
Return values
truethe_node is the first node on a chain.
falsethe_node is not the first node on a chain.

Definition at line 486 of file chain.h.

◆ rtems_chain_is_head()

static __inline__ bool rtems_chain_is_head ( const rtems_chain_control the_chain,
const rtems_chain_node the_node 
)
static

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_chainis the chain to be operated upon.
[in]the_nodeis the node to check for being the Chain Head.
Return values
truethe_node is the head of the_chain.
falsethe_node is not the head of the_chain.

Definition at line 541 of file chain.h.

◆ rtems_chain_is_last()

static __inline__ bool rtems_chain_is_last ( const rtems_chain_node the_node)
static

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_nodeis the node to check as the last node.
Return values
truethe_node is the last node on a chain.
falsethe_node is not the last node on a chain

Definition at line 504 of file chain.h.

◆ rtems_chain_is_node_off_chain()

static __inline__ bool rtems_chain_is_node_off_chain ( const rtems_chain_node node)
static

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]nodeis the node off chain.
Return values
trueThe node is off chain.
falseThe node is not off chain.

Definition at line 216 of file chain.h.

◆ rtems_chain_is_null_node()

static __inline__ bool rtems_chain_is_null_node ( const rtems_chain_node the_node)
static

Is the chain node pointer NULL.

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

Parameters
[in]the_nodeis the node pointer to check.
Return values
trueThe chain node pointer is NULL.
falseThe chain node pointer is not NULL.

Definition at line 233 of file chain.h.

◆ rtems_chain_is_tail()

static __inline__ bool rtems_chain_is_tail ( const rtems_chain_control the_chain,
const rtems_chain_node the_node 
)
static

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_chainis the chain to be operated upon.
[in]the_nodeis the node to check for being the Chain Tail.
Return values
truethe_node is the tail of the_chain.
falsethe_node is not the tail of the_chain.

Definition at line 561 of file chain.h.

◆ rtems_chain_last()

static __inline__ rtems_chain_node* rtems_chain_last ( const rtems_chain_control the_chain)
static

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_chainis the chain to be operated upon.
Returns
This method returns the last node of the chain.

Definition at line 348 of file chain.h.

◆ rtems_chain_next()

static __inline__ rtems_chain_node* rtems_chain_next ( const rtems_chain_node the_node)
static

Return pointer the next node from this node.

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

Parameters
[in]the_nodeis the node to be operated upon.
Returns
This method returns the next node on the chain.

Definition at line 381 of file chain.h.

◆ rtems_chain_node_count_unprotected()

static __inline__ size_t rtems_chain_node_count_unprotected ( const rtems_chain_control chain)
static

Returns the node count of the chain.

Parameters
[in]chainThe chain.
Note
It does NOT disable interrupts to ensure the atomicity of the operation.
Returns
The node count of the chain.

Definition at line 775 of file chain.h.

◆ rtems_chain_prepend()

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_chainis the chain to be operated upon.
[in]the_nodeis the node to be prepended.

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

◆ rtems_chain_prepend_unprotected()

static __inline__ void rtems_chain_prepend_unprotected ( rtems_chain_control the_chain,
rtems_chain_node the_node 
)
static

Prepend a node (unprotected).

This routine prepends the_node onto the front of the_chain.

Parameters
[in]the_chainis the chain to be operated upon.
[in]the_nodeis the node to be prepended.

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

Definition at line 714 of file chain.h.

◆ rtems_chain_prepend_with_empty_check()

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
trueThe chain was empty before the prepend.
falseThe chain contained at least one node before the prepend.

◆ rtems_chain_prepend_with_notification()

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_SUCCESSFULSuccessful operation.
RTEMS_INVALID_IDNo such task.

◆ rtems_chain_previous()

static __inline__ rtems_chain_node* rtems_chain_previous ( const rtems_chain_node the_node)
static

Return pointer the previous node from this node.

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

Parameters
[in]the_nodeis the node to be operated upon.
Returns
This method returns the previous node on the chain.

Definition at line 413 of file chain.h.

◆ rtems_chain_set_off_chain()

static __inline__ void rtems_chain_set_off_chain ( rtems_chain_node node)
static

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]nodethe node set to off chain.

Definition at line 183 of file chain.h.

◆ rtems_chain_tail()

static __inline__ rtems_chain_node* rtems_chain_tail ( rtems_chain_control the_chain)
static

Return pointer to Chain Tail.

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

Parameters
[in]the_chainis the chain to be operated upon.
Returns
This method returns the permanent tail node of the chain.

Definition at line 281 of file chain.h.