#ifndef _apl_containers_slistapi_h_ #define _apl_containers_slistapi_h_ /*---------------------------------------------------------------------------- ** SUMMARY: Intrusive Single Linked List (ISLIST) ** ** DESCRIPTION: ** This file provides a TYPELESS (i.e. NOT type-safe) interface for ** a single-linked list of data structures. All items contained in the ** list must be of "type" ILNODE. See apl/containers/nodeapi.h for details. ** ** MEMORY: ** ------- ** The list mechanism is "intrusive", which means that the items being ** queued/contained must have foreknowledge of the fact there are going ** to be a list. This is because the items provide the memory for the ** list's link field(s). This is somewhat cumbersome, BUT its advantage is ** that NO dynamic memory allocation is needed/used by the list. ** ** ** CONFIGURATION ** ------------- ** COMPILE: none. ** ** APPLICATION: none. ** ** PLATFORM: none. ** ** ** NOTES: ** 1. For efficency/optimization some methods are 'inlined'. The inlining ** is done by using the preprocessor/macros. The application should ** treat all methods as function calls and not rely on the fact they may ** be currently defined as macros. ----------------------------------------------------------------------------*/ #include "apl/types/types.h" /* For: basic types */ #ifdef __cplusplus extern "C" { #endif /*-------------- TYPES -----------------------------------------------------*/ /** List structure */ typedef struct AplSlist_tag { void* _head; void* _tail; } AplSList; /** Handle to a Single-Linked List */ #define AplSListHdl AplSList* /*-------------- INLINE IMPLEMENTATION -------------------------------------*/ #include "apl/containers/slist.h" /* For: inline implementation */ /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ /** This method initializes the list. This method must be called BEFORE any other operation are called on the list. The application must provide an actual List INSTANCE (i.e. a reference to actual memory) to the list being initialized. Prototype: void Apl_slistInitialize( AplSList* listToInitialize ); */ #define Apl_slistInitialize _Apl_slistInitialize /** This method moves the entire content of the source-list to the the destination list. The source-list will be empty after this operation. Any previous contents of the destination-list are lost. Prototype: void Apl_slistMove( AplSListHdl src, AplSListHdl dst ); */ #define Apl_slistMove _Apl_slistMove /** This method empties the list. All references to the item(s) in the list are lost. Prototype: void Apl_slistClear( AplSListHdl list ); */ #define Apl_slistClear _Apl_slistClear /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ /* ** The following methods "view" the list a FIFO. */ /** This method removes the first item in the FIFO. Returns 0 if the FIFO is empty. Prototype void* Apl_slistGet( AplSListHdl fifo ); */ #define Apl_slistGet _Apl_slistGet /** This methods adds the item as the last item in the FIFO Prototype: void Apl_slistPut( AplSlistHdl fifo, void* newitem ); */ #define Apl_slistPut _Apl_slistPut /** This method returns a pointer to the first item in the FIFO. The returned item remains in the FIFO. Returns 0 if the FIFO is empty. Prototype: void* Apl_slistHead( AplSListHdl fifo ); */ #define Apl_slistHead _Apl_slistHead /** This method returns a pointer to the last item in the FIFO. The returned item remains in the FIFO. Returns 0 if the FIFO is empty. Prototype: void* Apl_slistTail( AplSListHdl fifo ); */ #define Apl_slistTail _Apl_slistTail /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ /* ** The following methods "view" the list a Stack */ /** This method removes the top element from stack and return a pointer to it as a result. Returns 0, if the stack is empty. Prototype: void* Apl_slistPop( AplSListHdl stack ); */ #define Apl_slistPop _Apl_slistPop /** This method adds the item to top of the stack. Prototype: void Apl_slistPush( AplSListHdl stack, void* itemToPush ); */ #define Apl_slistPush _Apl_slistPush /** This method returns a pointer to the top item in the stack. The returned item remains in the queue. Returns 0 if the stack is empty. Prototype: void* Apl_slistTop( AplSListHdl stack ); */ #define Apl_slistTop _Apl_slistTop /*-------------- PUBLIC/PUBLISHED API --------------------------------------*/ /* ** The following methods "view" the list an Ordered List. */ /** This method removes the first item in the list. Returns 0 if the list is empty. Prototype: void* Apl_slistGetFirst( AplSListHdl list ); */ #define Apl_slistGetFirst _Apl_slistGetFirst /** This method removes the last item in the list. Returns 0 if the list is empty. Prototype: void* Apl_slistGetLast( AplSListHdl list ); */ #define Apl_slistGetLast _Apl_slistGetLast /** This method adds the item as the first item in the list. Prototype: void Apl_slistPutFirst( AplSListHdl list, void* itemToAdd ); */ #define Apl_slistPutFirst _Apl_slistPutFirst /** This method adds the item as the last item in the list. Prototype: void Apl_slistPutLast( AplSListHdl list, void* itemToAdd ); */ #define Apl_slistPutLast _Apl_slistPutLast /** This method removes specified element from the list. Returns non-zero (true), if the specified element was foumd and removed from the list, else 0 (false). Note: This method does an internal search/walk of the list. Prototype: AplBool Apl_slistRemove( AplSListHdl list, void* itemToRemove ); */ #define Apl_slistRemove _Apl_slistRemove /** This method inserts the specified item into the list behind the 'after' element. If 'after' is 0, then the item is added to the head of the list. It is ASSUMED that the 'after' element is in the list if it is not 0. Prototype: void Apl_slistInsertAfter( AplSListHdl list, void* itemToAdd, void* afterItem ); */ #define Apl_slistInsertAfter _Apl_slistInsertAfter /** This method inserts the specified item into the list ahead the 'before' element. If 'before' is 0, then the item is added to the tail of the list. Since this is single-linked list, the method does a search for the 'before' element. If the before element is found, the insertion takes place and non-zero (true) is returend, else 0 (false) is returned. Prototype: AplBool Apl_slistInsertBefore( AplSListHdl list, void* itemToAdd, void* beforeItem ); */ #define Apl_slistInsertBefore _Apl_slistInsertBefore /** This method returns non-zero (true) of the specified item is already in the list, else 0 (false) is returend. Prototype: AplBool Apl_slistFind( AplSListHdl list, void* itemToSearchFor ); */ #define Apl_slistFind _Apl_slistFind /** This method returns a pointer to the first item in the list. The returned item remains in the list. Returns 0 if the list is empty. Prototype: void* Apl_slistFirst( AplSListHdl list ); */ #define Apl_slistFirst _Apl_slistFirst /** This method returns a pointer to the last item in the list. The returned item remains in the list. Returns 0 if the list is empty. Prototype: void* Apl_slistLast( AplSListHdl list ); */ #define Apl_slistLast _Apl_slistLast /** This method returns a pointer to the item after 'currentItem' . Both items remain in the list. Returns 0 when the end-of-list is reached. This method is used to traverse/walk the list. Prototype: void* Apl_slistNext( void* currentItem ); */ #define Apl_slistNext _Apl_slistNext #ifdef __cplusplus } #endif /*--------------------------------------------------------------------------*/ #endif /* end _apl_containers_slistapi_h_ */