Chain Handler

This group contains the Chain Handler implementation. More...

Files
file	chain.h
	This header file provides interfaces of the Chain Handler which are used by the implementation and the API.
file	chainimpl.h
	This header file provides interfaces of the Chain Handler which are only used by the implementation.
file	chain.c
	This source file contains the implementation of _Chain_Initialize().
file	chainnodecount.c
	This source file contains the implementation of _Chain_Node_count_unprotected().

Data Structures
struct	Chain_Node
	This structure represents a chain node. More...
union	Chain_Control
	This union represents a chain control block. More...
struct	Chain_Iterator
	A chain iterator which is updated during node extraction if it is properly registered. More...
struct	Chain_Iterator_registry
	A registry for chain iterators. More...

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

Typedefs
typedef struct Chain_Node	Chain_Node
	This structure represents a chain node.
typedef bool(*	Chain_Node_order) (const void *key, const Chain_Node *left, const Chain_Node *right)
	Chain node order.

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

Functions
void	_Chain_Initialize (Chain_Control *the_chain, void *starting_address, size_t number_nodes, size_t node_size)
	Initializes a chain header.
size_t	_Chain_Node_count_unprotected (const Chain_Control *chain)
	Returns the node count of the chain.

Detailed Description

This group contains the Chain Handler implementation.

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

Macro Definition Documentation

CHAIN_INITIALIZER_ONE_NODE

#define CHAIN_INITIALIZER_ONE_NODE

(

node

)

{ { { (node), NULL }, (node) } }

Chain initializer for a chain with one node.

See also

CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN().

CHAIN_ITERATOR_REGISTRY_INITIALIZER

#define CHAIN_ITERATOR_REGISTRY_INITIALIZER

(

name

)

{ CHAIN_INITIALIZER_EMPTY( name.Iterators ) }

Chain iterator registry initializer for static initialization.

Parameters

name	The designator of the chain iterator registry.

CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN

#define CHAIN_NODE_INITIALIZER_ONE_NODE_CHAIN

(

chain

)

{ &(chain)->Tail.Node, &(chain)->Head.Node }

Chain node initializer for a chain containing exactly this node.

See also

CHAIN_INITIALIZER_ONE_NODE().

Typedef Documentation

Chain_Node

typedef struct Chain_Node Chain_Node

This structure represents a chain node.

This is used to manage each element (node) which is placed on a chain.

Note

Typically, a more complicated structure will use the chain package. The more complicated structure will include a chain node as the first element in its control structure. It will then call the chain package with a pointer to that node element. The node pointer and the higher level structure start at the same address so the user can cast the pointers back and forth.

Chain_Node_order

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

Chain node order.

Parameters

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

Return values

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

Enumeration Type Documentation

Chain_Iterator_direction

enum Chain_Iterator_direction

The chain iterator direction.

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

Function Documentation

_Chain_Initialize()

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

Initializes a chain header.

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

Parameters

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

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