EGlist

---

Detailed Description

Here are deffined the basic interface for a double linked list with external data asociated to each node in the list.

History:

Revision 0.0.2

• 2003-07-02
  • Add attach/unattach interface.
• 2003-06-11
  • Modified to use the general list code eg_listint.h
  • Add inline support for most of the functions.
• 2003-05-22
  • Modified EGfreeListNode and others to handle nullFree correctly
• 2003-05-05
  • (Marcos) Added the MP (memPool) versions of EGlistErase, EGlistClear, and EGfreeListNode. These versions allow the destructor passed to the function to use a memory pool manager as well.
  • Added function EGlistMoveNode, to move a node (with its internal data) from one list to another different list. Revision 0.0.1
• 2003-04-10

Note:

In general, the functions described bellow don't perform consistency checks. It is asumed that the user does know what is he doing.

If you want to have some debugging control try changing the debug level at compile time, and lowering the debug level asociated to the list function as defined in eg_configure.h.

Files
file	eg_list.h
Data Structures
struct	EGlist_t
	List Basic Structure. More...
struct	EGlistNode_t__
	List Node Structure. More...
Defines
#define	EGclistGetNextIt(list, node)   ((node)->next ? (node)->next : (list)->begin)
	Given a list and a node_iterator return the next node iterator of the list but in a circular way.
#define	EGclistRoot(list)   ((list)->begin)
Typedefs
typedef EGlistNode_t__	EGlistNode_t
	List Node Structure.
Functions
void	EGfreeList (void *mylist)
	Return the list's memory to the memory pool.
void	EGfreeListNode (void *localNode, EGmemPool_t *mypool)
	Return the list node memory to the memory pool.
void	EGfreeListNodeMP (void *localNode, EGfreeMP_f dataFree, EGmemPool_t *structmem, EGmemPool_t *datamem)
	Free one node and return the internal data to the specified memory pool.
int	EGlistAttach (EGlist_t *list, EGlistNode_t *eg_node)
	attach a node to the list at the end of the list
int	EGlistClear (EGlist_t *mylist, EGfree_f dataFree)
	given an initialized list, left it at its initial state (just after EGnewList).
int	EGlistClearMP (EGlist_t *mylist, EGfreeMP_f dataFree, EGmemPool_t *datamem)
	Clean out the list and leave it in its original state, the internal memory is returned to the provided memory pool.
void *	EGlistCopy (void *source)
	Create a copy of the given list using as memory pool the memory pool of the given list.
int	EGlistErase (EGlist_t *mylist, EGlistNode_t *mynode, EGfree_f dataFree)
	Eliminate one node form the list.
int	EGlistEraseMP (EGlist_t *mylist, EGlistNode_t *mynode, EGfreeMP_f dataFree, EGmemPool_t *datamem)
	Erase a node from the list and retunr internal data to a specified memory pool.
EGlistNode_t *	EGlistFind (EGlist_t *mylist, const void *mem)
	Look for a user data pointer in the provided list.
int	EGlistInsertAfter (EGlist_t *mylist, EGlistNode_t *node, void *data)
	Add to the list a new node pointing to the provided data that is after the given node in the list.
int	EGlistInsertBefore (EGlist_t *mylist, EGlistNode_t *node, void *data)
	Add to the list a new node pointing to the provided data that is before the given node in the list.
int	EGlistLink (EGlist_t *dlist, EGlist_t *olist)
	Move the contents of the second list into the tail of the first list.
int	EGlistMoveNode (EGlist_t *sourceList, EGlist_t *destList, EGlistNode_t *localNode)
	move anode from one list to the end of another.
int	EGlistPushBack (EGlist_t *mylist, void *data)
	Add to the (end of the) list a new node pointing to the provided data.
int	EGlistPushHead (EGlist_t *mylist, void *data)
	Add to the (begining of the) list a new node pointing to the provided data.
int	EGlistUnattach (EGlist_t *list, EGlistNode_t *eg_node)
	unattach a node from the list, without erasing it
EGlist_t *	EGnewList (EGmemPool_t *mypool)
	alloc a new initialized list.

---

Define Documentation

#define EGclistGetNextIt (  list, node   )     ((node)->next ? (node)->next : (list)->begin)

Given a list and a node_iterator return the next node iterator of the list but in a circular way. Parameters: list  EGlist_t* pointer to the list. node  EGlistNode_t* pointer to the current iterator in the list. Returns: EGlistNode_t* pointer to the next iterator in the (circular) list. Description: Given a list and a node_iterator return the next node iterator of the list but in a circular way. thus the result of the next of the tail, is the head of the list. Definition at line 94 of file eg_list.h.

#define EGclistRoot (  list   )     ((list)->begin)

Definition at line 95 of file eg_list.h.

---

Typedef Documentation

typedef struct EGlistNode_t__ EGlistNode_t

List Node Structure. Description: This structure is to store a general node of the list. It is composed by three members, one to store external or satelite data, and the others to to point to the next and previous structures in the list.

---

Function Documentation

void EGfreeList (  void *  mylist  )  [inline]

Return the list's memory to the memory pool. Parameters: mylist  Pointer to an initialized list to be returned to the mempool. Description: This function return to the construction pool all memory used by the list, this function _MUST_ be used for every EGlist allocated by 'EGnewList'. Note that the memory bointed by the internall data will not be freed, to free internal memory, first use EGlistClear(). Definition at line 153 of file eg_list.h.

void EGfreeListNode (  void *  localNode, EGmemPool_t *  mypool )  [inline]

Return the list node memory to the memory pool. Parameters: localNode  Node to be freed (returned to the memory pool). mypool  Pointer of the memory manager where we will return the memory of the node. Description: This function return to the pool an unused EGlistNode, this function _MUST_ be used for every EGlistNode allocated by 'EGnewListNode', you should not use this function, if you use it, is at your own risk. Definition at line 173 of file eg_list.h.

void EGfreeListNodeMP (  void *  localNode, EGfreeMP_f  dataFree, EGmemPool_t *  structmem, EGmemPool_t *  datamem )  [inline]

Free one node and return the internal data to the specified memory pool. Parameters: localNode  Node to be freed, the memory used by it will be returned to the 'structmem' memory pool. dataFree  Pointer to the function that free the internal data of the node to the 'datamem' memory pool. structmem  Pointer to the memory pool where the list structure memory will be returned. datamem  Pointer to the memory pool where the internal data memory will be returned. Description: This function return to the pool an unused EGlistNode, this function _MUST_ be used for every EGlistNode allocated by 'EGnewListNode'. The list structures will be liberate to the list memory manager, and the internal data will be liberated to the 'datamem' memory pool. Definition at line 283 of file eg_list.h.

int EGlistAttach (  EGlist_t *  list, EGlistNode_t *  eg_node )  [inline]

attach a node to the list at the end of the list Parameters: list  List where we will add the node. eg_node  node to be added to the tail of the list. Returns: zero on success, non zero otherwise. Description: Given a list and an initialized node, it put at the end of the list the node. Definition at line 470 of file eg_list.h.

int EGlistClear (  EGlist_t *  mylist, EGfree_f  dataFree )  [inline]

given an initialized list, left it at its initial state (just after EGnewList). Parameters: mylist  Pointer to an initialized list to be cleared. dataFree  Pointer to a function that free the internal data stored in the nodes of the list. It can be the null function (nullFree), in which case we don't touch the internal data at all. Returns: zero on success, nonzero otherwise. Description: This function left the list empty, and call 'dataFree' to liberate the external data stored in the node of the list Definition at line 222 of file eg_list.h.

int EGlistClearMP (  EGlist_t *  mylist, EGfreeMP_f  dataFree, EGmemPool_t *  datamem )  [inline]

Clean out the list and leave it in its original state, the internal memory is returned to the provided memory pool. Parameters: mylist  Pointer to the list that is going to be cleaned. dataFree  Pointer to the function that free the internal data structured to the provided memory pool. datamem  Pointer to the memory manager where we will return the internal memory. Description: This function left the list empty The list structures will be liberate to the list memory manager, and the internal data will be liberated to the 'datamem' memory pool. Definition at line 309 of file eg_list.h.

void* EGlistCopy (  void *  source  )  [inline]

Create a copy of the given list using as memory pool the memory pool of the given list. Parameters: source  Pointer to the list to be copied, note that this copier don't create copies of the pointed elements, but just copy the pointers to them in the new list. Returns: Pointer to the copy list. Description: Given a list, it creates a copy of such list but does not create copies of the 'this' fields, but just copy its values. The memory pool used is the same as the memory pool of the source list. The function complies with the EGcopy_f prototype so it can be called in other copiers. Definition at line 520 of file eg_list.h. Here is the call graph for this function:

int EGlistErase (  EGlist_t *  mylist, EGlistNode_t *  mynode, EGfree_f  dataFree )  [inline]

Eliminate one node form the list. Parameters: mylist  List from where we will eliminate the node 'mynode'. mynode  Node to be eliminate from the list. dataFree  Pointer to a function that free the internal data memory stored in the node, it can be NUNLL, in whose case it is not executed and the the internal data is not touched at all. Returns: zero on success, nonzero otherwise. Description: This function erase an element pointed by an EGlistNode_t from the list where this node bellongs. Warning: Note that this function __WILL_NOT__ check if the node really is in the list, that is up to you, use with precuation. Definition at line 197 of file eg_list.h.

int EGlistEraseMP (  EGlist_t *  mylist, EGlistNode_t *  mynode, EGfreeMP_f  dataFree, EGmemPool_t *  datamem )  [inline]

Erase a node from the list and retunr internal data to a specified memory pool. Parameters: mylist  Pointer to the list from where we will eliminate a node. mynode  Pointer to the node to be eliminated from the specified list. dataFree  Pointer to a function that free the internal (or satelite) data of the node to the memory pool specified. This function can be nullFreeMP, in which case we don't touch the internal data at all. datamem  Pointer to the memory pool where we will return the memory used by the internal data, it is passed as the second argument for dataFree. Returns: zero on success, nonzero otherwise. Description: this is to erase an element pointed by an EGlistNode from the list where this node bellongs. Note that this function __WILL_NOT__ check if the node really is in the list, that is up to you, use with precuation. The list structures will be liberate to the list memory manager, and the internal data will be liberated to the 'datamem' memory pool. Definition at line 252 of file eg_list.h.

EGlistNode_t* EGlistFind (  EGlist_t *  mylist, const void *  mem )  [inline]

Look for a user data pointer in the provided list. Parameters: mylist  Pointer to an initialized list where we will look for the user data pointer. mem  Pointer to be looked for in the list. Returns: pointer to the EGlistNode_t that contains the desired element in the list, otherwise it returns zero. Description: This function look for something in the list, return the pointer to the EGlistNode_t* if the search is succesfull, zero otherwise. If it find the memory address, it store in the node the pointer to the node containing that address Definition at line 493 of file eg_list.h.

int EGlistInsertAfter (  EGlist_t *  mylist, EGlistNode_t *  node, void *  data )  [inline]

Add to the list a new node pointing to the provided data that is after the given node in the list. Parameters: mylist  Pointer to an initialized list where we will add the user data. node  Pointer to the node that will precede the inserted node. data  Pointer to the user data to be stored in the list. Description: Returns: zero in success, nonzero otherwise. Given an initialized list this will insert a new node at the begin of the list with 'this' pointing to 'data', note that we will not copy the data, but rather mantain a pointer to the user data. Definition at line 429 of file eg_list.h.

int EGlistInsertBefore (  EGlist_t *  mylist, EGlistNode_t *  node, void *  data )  [inline]

Add to the list a new node pointing to the provided data that is before the given node in the list. Parameters: mylist  Pointer to an initialized list where we will add the user data. node  Pointer to the node that will precede the inserted node. data  Pointer to the user data to be stored in the list. Description: Returns: zero in success, nonzero otherwise. Given an initialized list this will insert a new node at the begin of the list with 'this' pointing to 'data', note that we will not copy the data, but rather mantain a pointer to the user data. Definition at line 404 of file eg_list.h.

int EGlistLink (  EGlist_t *  dlist, EGlist_t *  olist )  [inline]

Move the contents of the second list into the tail of the first list. Parameters: dlist  list where all elements will be put together. olist  list from where elements will be taken out. Returns: zero on success and nonzero if an error occurs. Description: Given a destination list (dlist) and an origin list (olist) this function moves (without altering the original ordering) the elements of olist to the tail of dlist, leaving olist as an empty (and valid) list. Definition at line 548 of file eg_list.h.

int EGlistMoveNode (  EGlist_t *  sourceList, EGlist_t *  destList, EGlistNode_t *  localNode )  [inline]

move anode from one list to the end of another. Parameters: sourceList  Pointer to an initialized list from where we will take out a node. destList  Pointer to an initialized list where we will add the node. localNode  Pointer to the node to be moved. Description: This function moves a node from one list to another list, both list don't need to be differents, and that the pointer to the listNode to be valid an belong to the source list. The node will be placed at the end of the destine list. Definition at line 334 of file eg_list.h.

int EGlistPushBack (  EGlist_t *  mylist, void *  data )  [inline]

Add to the (end of the) list a new node pointing to the provided data. Parameters: mylist  Pointer to an initialized list where we will add the user data. data  Pointer to the user data to be stored in the list. Description: Returns: zero in success, nonzero otherwise. Given an initialized list this will insert a new node at the end of the list with 'this' pointing to 'data', note that we will not copy the data, but rather mantain a pointer to the user data. Definition at line 357 of file eg_list.h.

int EGlistPushHead (  EGlist_t *  mylist, void *  data )  [inline]

Add to the (begining of the) list a new node pointing to the provided data. Parameters: mylist  Pointer to an initialized list where we will add the user data. data  Pointer to the user data to be stored in the list. Description: Returns: zero in success, nonzero otherwise. Given an initialized list this will insert a new node at the begin of the list with 'this' pointing to 'data', note that we will not copy the data, but rather mantain a pointer to the user data. Definition at line 380 of file eg_list.h.

int EGlistUnattach (  EGlist_t *  list, EGlistNode_t *  eg_node )  [inline]

unattach a node from the list, without erasing it Parameters: list  List from where we will remove the node. eg_node  node to be eliminated from the list. Returns: zero on success non zero otherwise. Description: This function takes a list and a node and eliminate the node from the list without erasing it. Definition at line 451 of file eg_list.h.

EGlist_t* EGnewList (  EGmemPool_t *  mypool  )  [inline]

alloc a new initialized list. Parameters: mypool  Memory manager from where all the list structures will be allocated. Returns: EGlist_t* A pointer to an initialized new list structure. Description: This function return a pointer to an initialized EGlist alloc'ed by mypool, also, all internal memory alloc'ed for the list will be generated from the pool. Definition at line 125 of file eg_list.h.

---