threadutil: Doxygenation and compiler warnings.
(cherry picked from commit 7c524df1d9)
This commit is contained in:
Marcelo Roberto Jimenez
@@ -29,323 +29,257 @@
|
||||
*
|
||||
******************************************************************************/
|
||||
|
||||
|
||||
#ifndef LINKED_LIST_H
|
||||
#define LINKED_LIST_H
|
||||
|
||||
|
||||
/*!
|
||||
* \file
|
||||
*/
|
||||
|
||||
|
||||
#include "FreeList.h"
|
||||
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
|
||||
#define EOUTOFMEM (-7 & 1<<29)
|
||||
|
||||
|
||||
#define FREELISTSIZE 100
|
||||
#define LIST_SUCCESS 1
|
||||
#define LIST_FAIL 0
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Name: free_routine
|
||||
*
|
||||
* Description:
|
||||
* Function for freeing list items
|
||||
*****************************************************************************/
|
||||
/*! Function for freeing list items. */
|
||||
typedef void (*free_function)(void *arg);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Name: cmp_routine
|
||||
*
|
||||
* Description:
|
||||
* Function for comparing list items
|
||||
* Returns 1 if itemA==itemB
|
||||
*****************************************************************************/
|
||||
/*! Function for comparing list items. Returns 1 if itemA==itemB */
|
||||
typedef int (*cmp_routine)(void *itemA,void *itemB);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Name: ListNode
|
||||
*
|
||||
* Description:
|
||||
* linked list node. stores generic item and pointers to next and prev.
|
||||
* Internal Use Only.
|
||||
*****************************************************************************/
|
||||
/*! Linked list node. Stores generic item and pointers to next and prev.
|
||||
* \internal
|
||||
*/
|
||||
typedef struct LISTNODE
|
||||
{
|
||||
struct LISTNODE *prev;
|
||||
struct LISTNODE *next;
|
||||
void *item;
|
||||
struct LISTNODE *prev;
|
||||
struct LISTNODE *next;
|
||||
void *item;
|
||||
} ListNode;
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Name: LinkedList
|
||||
/*!
|
||||
* Linked list (no protection).
|
||||
*
|
||||
* Description:
|
||||
* linked list (no protection). Internal Use Only.
|
||||
* Because this is for internal use, parameters are NOT checked for
|
||||
* validity.
|
||||
* The first item of the list is stored at node: head->next
|
||||
* The last item of the list is stored at node: tail->prev
|
||||
* If head->next=tail, then list is empty.
|
||||
* To iterate through the list:
|
||||
* Because this is for internal use, parameters are NOT checked for validity.
|
||||
* The first item of the list is stored at node: head->next
|
||||
* The last item of the list is stored at node: tail->prev
|
||||
* If head->next=tail, then list is empty.
|
||||
* To iterate through the list:
|
||||
*
|
||||
* LinkedList g;
|
||||
* ListNode *temp = NULL;
|
||||
* for (temp = ListHead(g);temp!=NULL;temp = ListNext(g,temp))
|
||||
* {
|
||||
* }
|
||||
* LinkedList g;
|
||||
* ListNode *temp = NULL;
|
||||
* for (temp = ListHead(g);temp!=NULL;temp = ListNext(g,temp)) {
|
||||
* }
|
||||
*
|
||||
*****************************************************************************/
|
||||
* \internal
|
||||
*/
|
||||
typedef struct LINKEDLIST
|
||||
{
|
||||
ListNode head; /* head, first item is stored at: head->next */
|
||||
ListNode tail; /* tail, last item is stored at: tail->prev */
|
||||
long size; /* size of list */
|
||||
FreeList freeNodeList; /* free list to use */
|
||||
free_function free_func; /* free function to use */
|
||||
cmp_routine cmp_func; /* compare function to use */
|
||||
/*! head, first item is stored at: head->next */
|
||||
ListNode head;
|
||||
/*! tail, last item is stored at: tail->prev */
|
||||
ListNode tail;
|
||||
/*! size of list */
|
||||
long size;
|
||||
/*! free list to use */
|
||||
FreeList freeNodeList;
|
||||
/*! free function to use */
|
||||
free_function free_func;
|
||||
/*! compare function to use */
|
||||
cmp_routine cmp_func;
|
||||
} LinkedList;
|
||||
|
||||
/*!
|
||||
* \brief Initializes LinkedList. Must be called first and only once for List.
|
||||
*
|
||||
* \return
|
||||
* \li \c 0 on success.
|
||||
* \li \c EOUTOFMEM on failure.
|
||||
*/
|
||||
int ListInit(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Function used to compare items. (May be NULL). */
|
||||
cmp_routine cmp_func,
|
||||
/*! Function used to free items. (May be NULL). */
|
||||
free_function free_func);
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListInit
|
||||
/*!
|
||||
* \brief Adds a node to the head of the list. Node gets immediately after
|
||||
* list head.
|
||||
*
|
||||
* Description:
|
||||
* Initializes LinkedList. Must be called first.
|
||||
* And only once for List.
|
||||
* Parameters:
|
||||
* list - must be valid, non null, pointer to a linked list.
|
||||
* cmp_func - function used to compare items. (May be NULL)
|
||||
* free_func - function used to free items. (May be NULL)
|
||||
* Returns:
|
||||
* 0 on success, EOUTOFMEM on failure.
|
||||
*****************************************************************************/
|
||||
int ListInit(LinkedList *list,cmp_routine cmp_func, free_function free_func);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListAddHead
|
||||
*
|
||||
* Description:
|
||||
* Adds a node to the head of the list.
|
||||
* Node gets immediately after list.head.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* void * item - item to be added
|
||||
* Returns:
|
||||
* The pointer to the ListNode on success, NULL on failure.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode *ListAddHead(LinkedList *list, void *item);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListAddTail
|
||||
*
|
||||
* Description:
|
||||
* Adds a node to the tail of the list.
|
||||
* Node gets added immediately before list.tail.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* void * item - item to be added
|
||||
* Returns:
|
||||
* The pointer to the ListNode on success, NULL on failure.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode *ListAddTail(LinkedList *list, void *item);
|
||||
* \return The pointer to the ListNode on success, NULL on failure.
|
||||
*/
|
||||
ListNode *ListAddHead(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Item to be added. */
|
||||
void *item);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListAddAfter
|
||||
/*!
|
||||
* \brief Adds a node to the tail of the list. Node gets added immediately
|
||||
* before list.tail.
|
||||
*
|
||||
* Description:
|
||||
* Adds a node after the specified node.
|
||||
* Node gets added immediately after bnode.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* void * item - item to be added
|
||||
* ListNode * bnode - node to add after
|
||||
* Returns:
|
||||
* The pointer to the ListNode on success, NULL on failure.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode *ListAddAfter(LinkedList *list, void *item, ListNode *bnode);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListAddBefore
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Adds a node before the specified node.
|
||||
* Node gets added immediately before anode.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* ListNode * anode - node to add the in front of.
|
||||
* void * item - item to be added
|
||||
* Returns:
|
||||
* The pointer to the ListNode on success, NULL on failure.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode *ListAddBefore(LinkedList *list,void *item, ListNode *anode);
|
||||
* \return The pointer to the ListNode on success, NULL on failure.
|
||||
*/
|
||||
ListNode *ListAddTail(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Item to be added. */
|
||||
void *item);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListDelNode
|
||||
/*!
|
||||
* \brief Adds a node after the specified node. Node gets added immediately
|
||||
* after bnode.
|
||||
*
|
||||
* Description:
|
||||
* Removes a node from the list
|
||||
* The memory for the node is freed.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* ListNode *dnode - done to delete.
|
||||
* freeItem - if !0 then item is freed using free function.
|
||||
* if 0 (or free function is NULL) then item is not freed
|
||||
* Returns:
|
||||
* The pointer to the item stored in the node or NULL if the item is freed.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
void *ListDelNode(LinkedList *list,ListNode *dnode, int freeItem);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListDestroy
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Removes all memory associated with list nodes.
|
||||
* Does not free LinkedList *list.
|
||||
* \return The pointer to the ListNode on success, NULL on failure.
|
||||
*/
|
||||
ListNode *ListAddAfter(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Item to be added. */
|
||||
void *item,
|
||||
/*! Node to add after. */
|
||||
ListNode *bnode);
|
||||
|
||||
/*!
|
||||
* \brief Adds a node before the specified node. Node gets added immediately
|
||||
* before anode.
|
||||
*
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* \return The pointer to the ListNode on success, NULL on failure.
|
||||
*/
|
||||
ListNode *ListAddBefore(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Item to be added. */
|
||||
void *item,
|
||||
/*! Node to add in front of. */
|
||||
ListNode *anode);
|
||||
|
||||
/*!
|
||||
* \brief Removes a node from the list. The memory for the node is freed.
|
||||
*
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* \return The pointer to the item stored in the node or NULL if the item
|
||||
* is freed.
|
||||
*/
|
||||
void *ListDelNode(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Node to delete. */
|
||||
ListNode *dnode,
|
||||
/*! if !0 then item is freed using free function. If 0 (or free
|
||||
* function is NULL) then item is not freed. */
|
||||
int freeItem);
|
||||
|
||||
/*!
|
||||
* \brief Removes all memory associated with list nodes. Does not free
|
||||
* LinkedList *list.
|
||||
*
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* \return 0 on success, EINVAL on failure.
|
||||
*/
|
||||
int ListDestroy(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! if !0 then item is freed using free function. If 0 (or free
|
||||
* function is NULL) then item is not freed. */
|
||||
int freeItem);
|
||||
|
||||
/*!
|
||||
* \brief Returns the head of the list.
|
||||
*
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* freeItem - if !0 then items are freed using the free_function.
|
||||
* if 0 (or free function is NULL) then items are not freed.
|
||||
* Returns:
|
||||
* 0 on success. Always returns 0.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
int ListDestroy(LinkedList *list, int freeItem);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListHead
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Returns the head of the list.
|
||||
* \return The head of the list. NULL if list is empty.
|
||||
*/
|
||||
ListNode *ListHead(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list);
|
||||
|
||||
/*!
|
||||
* \brief Returns the tail of the list.
|
||||
*
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
*
|
||||
* Returns:
|
||||
* The head of the list. NULL if list is empty.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode* ListHead(LinkedList *list);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListTail
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Returns the tail of the list.
|
||||
* \return The tail of the list. NULL if list is empty.
|
||||
*/
|
||||
ListNode *ListTail(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list);
|
||||
|
||||
/*!
|
||||
* \brief Returns the next item in the list.
|
||||
*
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
*
|
||||
* Returns:
|
||||
* The tail of the list. NULL if list is empty.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode* ListTail(LinkedList *list);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListNext
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Returns the next item in the list.
|
||||
* \return The next item in the list. NULL if there are no more items in list.
|
||||
*/
|
||||
ListNode *ListNext(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Node from the list. */
|
||||
ListNode *node);
|
||||
|
||||
/*!
|
||||
* \brief Returns the previous item in the list.
|
||||
*
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
*
|
||||
* Returns:
|
||||
* The next item in the list. NULL if there are no more items in list.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode* ListNext(LinkedList *list, ListNode * node);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListPrev
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* Description:
|
||||
* Returns the previous item in the list.
|
||||
*
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
*
|
||||
* Returns:
|
||||
* The previous item in the list. NULL if there are no more items in list.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode* ListPrev(LinkedList *list, ListNode * node);
|
||||
* \return The previous item in the list. NULL if there are no more items in list.
|
||||
*/
|
||||
ListNode *ListPrev(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! Node from the list. */
|
||||
ListNode *node);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListFind
|
||||
/*!
|
||||
* \brief Finds the specified item in the list.
|
||||
*
|
||||
* Description:
|
||||
* Finds the specified item in the list.
|
||||
* Uses the compare function specified in ListInit. If compare function
|
||||
* is NULL then compares items as pointers.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
* ListNode *start - the node to start from, NULL if to start from
|
||||
* beginning.
|
||||
* void * item - the item to search for.
|
||||
* Returns:
|
||||
* The node containing the item. NULL if no node contains the item.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
ListNode* ListFind(LinkedList *list, ListNode *start, void * item);
|
||||
|
||||
|
||||
/****************************************************************************
|
||||
* Function: ListSize
|
||||
* Uses the compare function specified in ListInit. If compare function
|
||||
* is NULL then compares items as pointers.
|
||||
*
|
||||
* Description:
|
||||
* Returns the size of the list.
|
||||
* Parameters:
|
||||
* LinkedList *list - must be valid, non null, pointer to a linked list.
|
||||
|
||||
* Returns:
|
||||
* The number of items in the list.
|
||||
* Precondition:
|
||||
* The list has been initialized.
|
||||
*****************************************************************************/
|
||||
int ListSize(LinkedList* list);
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* \return The node containing the item. NULL if no node contains the item.
|
||||
*/
|
||||
ListNode* ListFind(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList *list,
|
||||
/*! The node to start from, NULL if to start from beginning. */
|
||||
ListNode *start,
|
||||
/*! The item to search for. */
|
||||
void *item);
|
||||
|
||||
/*!
|
||||
* \brief Returns the size of the list.
|
||||
*
|
||||
* Precondition: The list has been initialized.
|
||||
*
|
||||
* \return The number of items in the list.
|
||||
*/
|
||||
long ListSize(
|
||||
/*! Must be valid, non null, pointer to a linked list. */
|
||||
LinkedList* list);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user