OpenSRF/src/libstack/osrf_list.h

   1 #ifndef OSRF_LIST_H
   2 #define OSRF_LIST_H
   3
   4
   5 #include <stdio.h>
   6 #include "opensrf/utils.h"
   7 #include <Judy.h>
   8
   9 /**
  10   Items are stored as void*'s so it's up to the user to
  11   manage the data wisely.  Also, if the 'freeItem' callback is defined for the list,
  12   then, it will be used on any item that needs to be freed, so don't mix data
  13   types in the list if you want magic freeing */
  14
  15 struct __osrfListStruct {
  16         Pvoid_t list;                                                   /* the list */
  17         int size;                                                               /* how many items in the list including NULL items between non-NULL items */
  18         void (*freeItem) (void* item);  /* callback for freeing stored items */
  19 };
  20 typedef struct __osrfListStruct osrfList;
  21
  22
  23 struct __osrfListIteratorStruct {
  24         osrfList* list;
  25         unsigned long current;
  26 };
  27 typedef struct __osrfListIteratorStruct osrfListIterator;
  28
  29
  30 /**
  31   Creates a new list iterator with the given list
  32   */
  33 osrfListIterator* osrfNewListIterator( osrfList* list );
  34
  35 /**
  36   Returns the next non-NULL item in the list, return NULL when
  37   the end of the list has been reached
  38   */
  39 void* osrfListIteratorNext( osrfListIterator* itr );
  40
  41 /**
  42   Deallocates the given list
  43   */
  44 void osrfListIteratorFree( osrfListIterator* itr );
  45
  46 void osrfListIteratorReset( osrfListIterator* itr );
  47
  48
  49 /**
  50   Allocates a new list
  51   @param compress If true, the list will compress empty slots on delete.  If item positionality
  52   is not important, then using this feature is reccomended to keep the list from growing indefinitely.
  53   if item positionality is not important.
  54   @return The allocated list
  55   */
  56 osrfList* osrfNewList();
  57
  58 /**
  59   Pushes an item onto the end of the list.  This always finds the highest index
  60   in the list and pushes the new item into the list after it.
  61   @param list The list
  62   @param item The item to push
  63   @return 0 on success, -1 on failure
  64   */
  65 int osrfListPush( osrfList* list, void* item );
  66
  67
  68 /**
  69  * Removes the last item in the list
  70  * See osrfListRemove for details on how the removed item is handled
  71  * @return The item, unless 'freeItem' exists, then returns NULL
  72  */
  73 void* osrfListPop( osrfList* list );
  74
  75 /**
  76   Puts the given item into the list at the specified position.  If there
  77   is already an item at the given position and the list has it's
  78   "freeItem" function defined, then it will be used to free said item.
  79   If no 'freeItem' callback is defined, then the displaced item will
  80   be returned;
  81   @param list The list
  82   @param item The item to put into the list
  83   @param position The position to place the item in
  84   @return NULL in successfully inserting the new item and freeing
  85   any displaced items.  Returns the displaced item if no "freeItem"
  86   callback is defined.
  87         */
  88 void* osrfListSet( osrfList* list, void* item, unsigned long position );
  89
  90 /**
  91   Returns the item at the given position
  92   @param list The list
  93   @param postiont the position
  94   */
  95 void* osrfListGetIndex( osrfList* list, unsigned long  position );
  96
  97 /**
  98   Frees the list and all list items (if the list has a "freeItem" function defined )
  99   @param list The list
 100   */
 101 void osrfListFree( osrfList* list );
 102
 103 /**
 104   Removes the list item at the given index
 105   @param list The list
 106   @param position The position of the item to remove
 107   @return A pointer to the item removed if "freeItem" is not defined
 108   for this list, returns NULL if it is.
 109   */
 110 void* osrfListRemove( osrfList* list, int position );
 111
 112 /**
 113   Finds the list item whose void* is the same as the one passed in
 114   @param list The list
 115   @param addr The pointer connected to the list item we're to find
 116   @return the index of the item, or -1 if the item was not found
 117   */
 118 int osrfListFind( osrfList* list, void* addr );
 119
 120
 121 void __osrfListSetSize( osrfList* list );
 122
 123
 124 /**
 125   @return The number of non-null items in the list
 126   */
 127 unsigned long osrfListGetCount( osrfList* list );
 128
 129 /**
 130  * May be used as a default memory freeing call
 131  * Just calls free() on list items
 132  */
 133 void osrfListVanillaFree( void* item );
 134
 135 /**
 136  * Tells the list to just call 'free()' on each item when
 137  * an item or the whole list is destroyed
 138  */
 139 void osrfListSetDefaultFree( osrfList* list );
 140
 141
 142 #endif