OpenSRF/src/libstack/osrf_list.h

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