include/opensrf/osrf_big_list.h

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