Linked List Utility Functions

Classes
struct	_OSRTSListNode
struct	_OSRTSList
Typedefs
typedef struct _OSRTSListNode	OSRTSListNode
typedef struct _OSRTSList	OSRTSList
Functions
void	rtxSListInit (OSRTSList *pList)
void	rtxSListInitEx (OSCTXT *pctxt, OSRTSList *pList)
void	rtxSListFree (OSRTSList *pList)
void	rtxSListFreeAll (OSRTSList *pList)
OSRTSList *	rtxSListCreate (OSVOIDARG)
OSRTSList *	rtxSListCreateEx (OSCTXT *pctxt)
OSRTSListNode *	rtxSListAppend (OSRTSList *pList, void *pData)
OSBOOL	rtxSListFind (OSRTSList *pList, void *pData)
void	rtxSListRemove (OSRTSList *pList, void *pData)

---

Detailed Description

Singly linked list structures have only a single link pointer and can therefore only be traversed in a single direction (forward). The node structures consume less memory than those of a doubly linked list.

Another difference between the singly linked list implementation and doubly linked lists is that the singly linked list uses conventional memory allocation functions (C malloc and free) for less storage instead of the rtxMem functions. Therefore, it is not a requirement to have an initialized context structure to work with these lists. However, performance may suffer if the lists become large due to the use of non-optimized memory management.

---

Function Documentation

OSRTSListNode* rtxSListAppend	(	OSRTSList *	pList,
		void *	pData
	)

This function appends an item to a linked list structure. The data item is passed into the function as a void parameter that can point to an object of any type.

Parameters:

	pList	A pointer to a linked list onto which the data item is to be appended.
	pData	A pointer to a data item to be appended to the list.

Returns:

A pointer to the allocated linked list structure.

OSRTSList* rtxSListCreate

(

OSVOIDARG

)

This function creates a new linked list structure. It allocates memory for the structure and calls rtxSListInit to initialize the structure.

Returns:

A pointer to the allocated linked list structure.

OSRTSList* rtxSListCreateEx

(

OSCTXT *

pctxt

)

The rtxSListAppend function appends an item to linked list structure. The data is passed into the function as a void that can point to an object of any type.

Parameters:

pctxt

A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.

Returns:

A pointer to the allocated linked list structure.

OSBOOL rtxSListFind	(	OSRTSList *	pList,
		void *	pData
	)

This function finds an item in the linked list structure. The data item is passed into the function as a void pointer that can point to an object of any type. If the appropriate node is found in the list this function returns TRUE, otherwise FALSE.

Parameters:

	pList	A pointer to a linked list onto which the data item is to be appended.
	pData	A pointer to a data item to be appended to the list.

Returns:

TRUE, if the node is found, otherwise FALSE.

void rtxSListFree

(

OSRTSList *

pList

)

This function removes all nodes from the linked list structure and releases memory that was allocated for storing node structures (OSRTSListNode). The data will not be freed.

Parameters:

pList

A pointer to a linked list onto which the data item is to be appended.

void rtxSListFreeAll

(

OSRTSList *

pList

)

This function removes all nodes from the linked list structure and releases memory that was allocated for storing node structures (OSRTSListNode). It also frees the data structures which are assumed to have been allocated using the rtxMemAlloc function.

Parameters:

pList

A pointer to a linked list onto which the data item is to be appended.

void rtxSListInit

(

OSRTSList *

pList

)

This function initializes a singly linked list structure. It sets the number of elements to zero and sets all internal pointer values to NULL.

Parameters:

pList

A pointer to a linked list structure to be initialized.

void rtxSListInitEx	(	OSCTXT *	pctxt,
		OSRTSList *	pList
	)

This function is similar to rtxSListInit but it also sets the pctxt (pointer to a context structure member of OSRTSList structure). This context will be used for further memory allocations; otherwise the standard malloc is used.

Parameters:

	pctxt	A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls.
	pList	A pointer to a linked list structure to be initialized.

void rtxSListRemove	(	OSRTSList *	pList,
		void *	pData
	)

This function finds an item in the linked list structure and removes it from the list. The data item is passed into the function as a void pointer that can point to an object of any type.

Parameters:

	pList	A pointer to a linked list onto which the data item is to be appended.
	pData	A pointer to a data item to be appended to the list.