• Main Page
  • Related Pages
  • Modules
  • Data Structures
  • Files
  • File List
  • Globals

sst/elements/genericProc/programs/libcprops/hashlist.h

Go to the documentation of this file.
00001 #ifndef _CP_HASHLIST_H
00002 #define _CP_HASHLIST_H
00003 
00004 /** @{ */
00005 /**
00006  * @file
00007  *
00008  * a mapping traversable by iterator - who could want more. access elements 
00009  * sequentially or by key. 
00010  */
00011 /* ----------------------------------------------------------------- */
00012 
00013 #include "common.h"
00014 
00015 __BEGIN_DECLS
00016 
00017 #include "config.h"
00018 
00019 #include "collection.h"
00020 #include "hashtable.h"
00021 
00022 /*************/
00023 
00024 typedef CPROPS_DLL struct _cp_hashlist_entry
00025 {
00026     void *key;                         /**< key of stored element */
00027     void *value;                       /**< stored element (content) */
00028     struct _cp_hashlist_entry *next;      /**< next entry */
00029     struct _cp_hashlist_entry *prev;      /**< previous entry */
00030     struct _cp_hashlist_entry *bucket;    /**< next record in bucket */
00031 } cp_hashlist_entry;
00032 
00033 
00034 /**
00035  * Main object that holds the endpoints of the hash-list and the hash-table.
00036  * 
00037  * It also stores the hash, compare and copy methods and the default
00038  * operation mode.
00039  */
00040 typedef CPROPS_DLL struct _cp_hashlist
00041 {
00042     cp_hashlist_entry **table;    /**< table of entries in the hash-table */
00043     cp_hashlist_entry *head;      /**< first item in the list */
00044     cp_hashlist_entry *tail;      /**< last item in the list */
00045     unsigned long table_size;     /**< size of the hash-table */
00046     unsigned long items;          /**< number of items in the collection */
00047 
00048     cp_hashfunction  hash_fn;     /**< pointer to hash function */
00049     cp_compare_fn    compare_fn;  /**< pointer to compare function */
00050     cp_copy_fn       copy_key;    /**< pointer to key copy function */
00051     cp_copy_fn       copy_value;  /**< pointer to value copy function */
00052         cp_destructor_fn free_key;
00053         cp_destructor_fn free_value;
00054 
00055     int mode;                     /**< operation mode (see collection.h) */
00056     cp_lock *lock;                                /**< lock */
00057         cp_thread txowner;                        /**< lock owner */
00058         int txtype;                   /**< lock type */
00059 
00060         unsigned long min_size;
00061         int fill_factor_min;              /**< minimal fill factor in percent */
00062         int fill_factor_max;              /**< maximal fill factor in percent */
00063 
00064 #if (CP_DEBUGLEVEL >= 2)
00065         cp_thread dtr_caller;
00066 #endif
00067 } cp_hashlist;
00068 
00069 /**
00070  * iterator for hashlists
00071  */
00072 typedef CPROPS_DLL struct _cp_hashlist_iterator
00073 {
00074     cp_hashlist *list;        /**< link to the list */
00075     cp_hashlist_entry **pos;   /**< current position */
00076 
00077     int lock_type;           /**< locking mode */
00078 } cp_hashlist_iterator;
00079 
00080 
00081 /*
00082  * Removes the entry with matching key and destroys it. 
00083  *
00084  * @param list the object
00085  * @param key  Key which is searched.
00086  * @param mode locking mode
00087  * @retval value that was stored in the entry.
00088  * @retval NULL if key was not found
00089  */
00090 CPROPS_DLL 
00091 void *cp_hashlist_remove_by_option(cp_hashlist *list, void *key, int mode);
00092 
00093 /**
00094  * Removes the first entry and destroys it. 
00095  *
00096  * @param list the object
00097  * @param mode locking mode
00098  * @return Element that was stored in the first entry.
00099  */
00100 CPROPS_DLL 
00101 void *cp_hashlist_remove_head_by_option(cp_hashlist *list, int mode);
00102 
00103 /**
00104  * Removes the last entry and destroys it. 
00105  *
00106  * @param list the object
00107  * @param mode locking mode
00108  * @return Element that was stored in the first entry.
00109  */
00110 CPROPS_DLL 
00111 void *cp_hashlist_remove_tail_by_option(cp_hashlist *list, int mode);
00112 
00113 /*************/
00114 
00115 /** default constructor */
00116 #define cp_hashlist_create(size_hint, hash_fn, compare_fn) \
00117         cp_hashlist_create_by_option(0, (size_hint), \
00118                                                                          (hash_fn), (compare_fn), \
00119                                                                          NULL, NULL, NULL, NULL)
00120 
00121 /**
00122  * constructor with parameters.
00123  *
00124  * @param operation mode bitmap (see collection.h)
00125  * @param size_hint initial size of the cp_hashtable 
00126  * @param hash_fn hash method  
00127  * @param compare_fn  hash compare method  
00128  */
00129 CPROPS_DLL 
00130 cp_hashlist *cp_hashlist_create_by_mode(int mode, 
00131                                                                                 unsigned long size_hint, 
00132                                                                                 cp_hashfunction hash_fn, 
00133                                                                                 cp_compare_fn compare_fn);
00134 
00135 /**
00136  * Constructor for copy mode.
00137  *
00138  * @param mode Bitmap of operation mode (see collection.h)
00139  * @param size_hint initial  size of the cp_hashtable 
00140  * @param hash_fn  hash method  
00141  * @param compare_fn   hash compare method  
00142  * @param copy_key   copy key method  
00143  * @param copy_value copy value method  
00144  */
00145 CPROPS_DLL 
00146 cp_hashlist *
00147         cp_hashlist_create_by_option(int mode, unsigned long size_hint, 
00148                                                  cp_hashfunction hash_fn, 
00149                                                                  cp_compare_fn compare_fn,
00150                                                                  cp_copy_fn copy_key, 
00151                                                                  cp_destructor_fn free_key,
00152                                                                  cp_copy_fn copy_value,
00153                                                                  cp_destructor_fn free_value);
00154 
00155 /**
00156  * Destroy the list with the mode stored in the list.
00157  */
00158 CPROPS_DLL 
00159 void cp_hashlist_destroy(cp_hashlist *);
00160 
00161 /**
00162  * Destroy the list with the mode stored in the list plus COLLECTION_MODE_DEEP.
00163  */
00164 CPROPS_DLL 
00165 void cp_hashlist_destroy_deep(cp_hashlist *);
00166 
00167 /**
00168  * Destroy the object with the specified mode (override default).
00169  *
00170  * @param list the object
00171  * @param mode locking mode
00172  */
00173 CPROPS_DLL 
00174 void cp_hashlist_destroy_by_option(cp_hashlist *list, int mode);
00175 
00176 /**
00177  * This function does exactly what you would think it does. Before it didn't - 
00178  * that was a bug. Now it does.
00179  */
00180 CPROPS_DLL 
00181 void cp_hashlist_destroy_custom(cp_hashlist *list, 
00182                                                                 cp_destructor_fn dk, 
00183                                                                 cp_destructor_fn dv);
00184 
00185 /**
00186  * iterates over the list and calls the callback function on each item.
00187  * 
00188  * @param list the hashlist
00189  * @param dk if not NULL, this function is invoked with the key for each entry
00190  * @param dv if not NULL, this function is invoked with the value for each entry
00191  */
00192 CPROPS_DLL 
00193 int cp_hashlist_callback(cp_hashlist *list, 
00194                                                  int (*cb)(void *key, void *value, void *id),
00195                                                  void *id);
00196 
00197 /**  find out what mode your cp_hashlist is running in */
00198 CPROPS_DLL 
00199 int cp_hashlist_get_mode(cp_hashlist *list);
00200 
00201 /** set the mode on your cp_hashlist */
00202 CPROPS_DLL 
00203 int cp_hashlist_set_mode(cp_hashlist *list, int mode);
00204 
00205 /** unset mode bits on list */
00206 CPROPS_DLL 
00207 int cp_hashlist_unset_mode(cp_hashlist *list, int mode);
00208 
00209 
00210 /**
00211  * the internal table will not be resized to less than min_size
00212  */
00213 CPROPS_DLL 
00214 int cp_hashlist_set_min_size(cp_hashlist *list, unsigned long min_size);
00215 
00216 /**
00217  * a resize is triggered when the table contains more items than
00218  * table_size * fill_factor / 100
00219  */
00220 CPROPS_DLL 
00221 int cp_hashlist_set_max_fill_factor(cp_hashlist *list, int fill_factor);
00222 
00223 /**
00224  * a resize is triggered when the table contains less items than
00225  * table_size * fill_factor / 100 if table_size > min_size
00226  */
00227 CPROPS_DLL 
00228 int cp_hashlist_set_min_fill_factor(cp_hashlist *list, int fill_factor);
00229 
00230 
00231 /* **************************************************************************
00232  *                                                                          *
00233  *                            iterator functions                            *
00234  *                                                                          *
00235  ************************************************************************** */
00236 
00237 /**
00238  * Create a new iterator and initialize it at the beginning.
00239  *
00240  * @param list list to iterate over
00241  * @param lock_mode locking mode to use
00242  * @return new iterator object
00243  */
00244 CPROPS_DLL 
00245 cp_hashlist_iterator *cp_hashlist_create_iterator(cp_hashlist *list, int lock_mode);
00246 
00247 /**
00248  * initialize the iterator at the beginning
00249  *
00250  * set the iterator at the beginning of the list and lock the list in the
00251  * mode specified in type.
00252  */
00253 CPROPS_DLL 
00254 int cp_hashlist_iterator_head(cp_hashlist_iterator *iterator);
00255 //int cp_hashlist_iterator_head(cp_hashlist_iterator *iterator, cp_hashlist *l, int lock_mode);
00256 
00257 CPROPS_DLL 
00258 int cp_hashlist_iterator_init(cp_hashlist_iterator *iterator, 
00259                                                           cp_hashlist *list, int type);
00260 /**
00261  * Initialize the Iterator at the end.
00262  *
00263  * Set the iterator at the end of the list and lock the list in the
00264  * mode specified in type.
00265  */
00266 CPROPS_DLL 
00267 int cp_hashlist_iterator_init_tail(cp_hashlist_iterator *iterator, cp_hashlist *l, int lock_mode);
00268 
00269 /**
00270  * set iterator at list tail
00271  */
00272 CPROPS_DLL 
00273 int cp_hashlist_iterator_tail(cp_hashlist_iterator *iterator);
00274 
00275 /**
00276  * set iterator position at first occurence of given key
00277  */
00278 CPROPS_DLL 
00279 int cp_hashlist_iterator_to_key(cp_hashlist_iterator *iterator, void *key);
00280 
00281 /**
00282  * iterator destructor
00283  */
00284 CPROPS_DLL 
00285 int cp_hashlist_iterator_destroy(cp_hashlist_iterator *iterator);
00286 
00287 /**
00288  * Unlock the list of the Iterator.
00289  *
00290  * If the locking mode is COLLECTION_LOCK_NONE, do nothing.
00291  */
00292 CPROPS_DLL 
00293 int cp_hashlist_iterator_release(cp_hashlist_iterator *iterator);
00294 
00295 
00296 /**
00297  * Go to the next entry in the list and return the content.
00298  * 
00299  * @retval entry the next entry object.
00300  * @retval NULL if reading beyond end or from empty list.
00301  */
00302 CPROPS_DLL 
00303 cp_hashlist_entry *cp_hashlist_iterator_next(cp_hashlist_iterator *iterator);
00304 
00305 /**
00306  * Go to the next entry in the list and return the key.
00307  * 
00308  * @return object of the next entry.
00309  * @retval NULL if reading beyond end or from empty list.
00310  */
00311 CPROPS_DLL 
00312 void *cp_hashlist_iterator_next_key(cp_hashlist_iterator *iterator);
00313 
00314 /**
00315  * Go to the next entry in the list and return the content.
00316  * 
00317  * @return object of the next entry.
00318  * @retval NULL if reading beyond end or from empty list.
00319  */
00320 CPROPS_DLL 
00321 void *cp_hashlist_iterator_next_value(cp_hashlist_iterator *iterator);
00322 
00323 /**
00324  * Go to the previous entry in the list and return the content.
00325  * 
00326  * @retval entry the previous entry object.
00327  * @retval NULL if reading beyond beginning or from empty list.
00328  */
00329 CPROPS_DLL 
00330 cp_hashlist_entry *cp_hashlist_iterator_prev(cp_hashlist_iterator *iterator);
00331 
00332 /**
00333  * Go to the previous entry in the list and return the key.
00334  * 
00335  * @return object of the previous entry.
00336  * @retval NULL if reading beyond beginning or from empty list.
00337  */
00338 CPROPS_DLL 
00339 void *cp_hashlist_iterator_prev_key(cp_hashlist_iterator *iterator);
00340 
00341 /**
00342  * Go to the previous entry in the list and return the content.
00343  * 
00344  * @return object of the previous entry.
00345  * @retval NULL if reading beyond beginning or from empty list.
00346  */
00347 CPROPS_DLL 
00348 void *cp_hashlist_iterator_prev_value(cp_hashlist_iterator *iterator);
00349 
00350 /**
00351  * return the entry at the current iterator position
00352  */
00353 CPROPS_DLL 
00354 cp_hashlist_entry *cp_hashlist_iterator_curr(cp_hashlist_iterator *iterator);
00355 
00356 /**
00357  * return the key at the current iterator position
00358  */
00359 CPROPS_DLL 
00360 void *cp_hashlist_iterator_curr_key(cp_hashlist_iterator *iterator);
00361 
00362 /**
00363  * return the value at the current iterator position
00364  */
00365 CPROPS_DLL 
00366 void *cp_hashlist_iterator_curr_value(cp_hashlist_iterator *iterator);
00367 
00368 
00369 /**
00370  * add a mapping before the current iterator position
00371  */
00372 CPROPS_DLL 
00373 cp_hashlist_entry *cp_hashlist_iterator_insert(cp_hashlist_iterator *iterator, 
00374                                                                                            void *key, 
00375                                                                                            void *value);
00376 /**
00377  * add a mapping after the current iterator position
00378  */
00379 CPROPS_DLL 
00380 cp_hashlist_entry *cp_hashlist_iterator_append(cp_hashlist_iterator *iterator, 
00381                                                                                            void *key,
00382                                                                                            void *value);
00383 
00384 /**
00385  * remove the mapping at the current iterator position
00386  */
00387 CPROPS_DLL 
00388 void *cp_hashlist_iterator_remove(cp_hashlist_iterator *iterator);
00389 
00390 
00391 /* ------------------------ end iterator functions ------------------------ */
00392 
00393 
00394 
00395 /**
00396  * Get the number of elements in the collection.
00397  * 
00398  * @return number of elements in the list.
00399  * @retval 0 if list is NULL
00400  */
00401 CPROPS_DLL 
00402 unsigned long cp_hashlist_item_count(cp_hashlist *);
00403 
00404 /**
00405  * Get the key of the entry.
00406  *
00407  * @note This function is fail-safe - works also on NULL entries.
00408  *       In any case you should check the result!
00409  *
00410  * @retval key of the entry.
00411  * @retval NULL if entry is NULL
00412  */
00413 CPROPS_DLL 
00414 void *cp_hashlist_entry_get_key(cp_hashlist_entry *entry);
00415 
00416 /**
00417  * Get the value of the entry.
00418  *
00419  * @note This function is fail-safe - works also on NULL entries.
00420  *       In any case you should check the result!
00421  *
00422  * @retval value of the entry.
00423  * @retval NULL if entry is NULL
00424  */
00425 CPROPS_DLL 
00426 void *cp_hashlist_entry_get_value(cp_hashlist_entry *entry);
00427 
00428 /**
00429  * Insert a new element (key, value) at the beginning of the list.
00430  * The operation is synchronized according to the properties of the object.
00431  *
00432  * @pre list != NULL
00433  * @pre key != NULL
00434  * @return value object
00435  */
00436 CPROPS_DLL 
00437 void *cp_hashlist_insert(cp_hashlist *list, void *key, void *value);
00438 
00439 /**
00440  * Insert a new element (key, value) at the beginning of the list with mode.
00441  * @return value object
00442  */
00443 CPROPS_DLL 
00444 void *cp_hashlist_insert_by_option(cp_hashlist *list, void *key, void *item, int mode);
00445 
00446 /**
00447  * Append a new element (key, value) at the end of the list.
00448  * The operation is synchronized according to the properties of the object.
00449  * @pre list != NULL
00450  * @pre key != NULL
00451  */
00452 CPROPS_DLL 
00453 void *cp_hashlist_append(cp_hashlist *list, void *key, void *value);
00454 
00455 /**
00456  * Append a new element (key, value) at the end of the list with mode.
00457  */
00458 CPROPS_DLL 
00459 void *cp_hashlist_append_by_option(cp_hashlist *, void *key, void *value, int mode);
00460 
00461 /**
00462  * Returns the first element with matching key.
00463  */
00464 CPROPS_DLL 
00465 void *cp_hashlist_get(cp_hashlist *, void *key);
00466 
00467 /**
00468  * returns non-zero if list contains key
00469  */
00470 CPROPS_DLL 
00471 int cp_hashlist_contains(cp_hashlist *list, void *key);
00472 
00473 /**
00474  * Returns the first element of the list.
00475  */
00476 CPROPS_DLL 
00477 void *cp_hashlist_get_head(cp_hashlist *);
00478 
00479 /**
00480  * Returns the last element of the list.
00481  */
00482 CPROPS_DLL 
00483 void *cp_hashlist_get_tail(cp_hashlist *);
00484 
00485 /**
00486  * Removes the entry with matching key and destroys it (internal locking mode). 
00487  *
00488  * @param list the object
00489  * @param key  Key which is searched.
00490  * @retval value that was stored in the entry.
00491  * @retval NULL if key was not found
00492  */
00493 CPROPS_DLL 
00494 void *cp_hashlist_remove(cp_hashlist *list, void *key);
00495 
00496 CPROPS_DLL 
00497 void *cp_hashlist_remove_deep(cp_hashlist *list, void *key);
00498 
00499 
00500 /**
00501  * Removes the entry with matching key and destroys it with locking mode.
00502  *
00503  * @param list the object
00504  * @param key  Key which is searched.
00505  * @param mode locking mode
00506  * @retval value that was stored in the entry.
00507  * @retval NULL if key was not found
00508  */
00509 CPROPS_DLL 
00510 void *cp_hashlist_remove_by_option(cp_hashlist *list, void *key, int mode);
00511 
00512 /**
00513  * Removes the first entry and destroys it. 
00514  *
00515  * @return Element that was stored in the first entry.
00516  */
00517 CPROPS_DLL 
00518 void *cp_hashlist_remove_head(cp_hashlist *list);
00519 
00520 /**
00521  * Removes the last entry and destroys it. 
00522  *
00523  * @pre list != NULL
00524  * @retval Element that was stored in the first entry if not empty.
00525  * @retval NULL if collection is empty
00526  */
00527 CPROPS_DLL 
00528 void *cp_hashlist_remove_tail(cp_hashlist *list);
00529 
00530 /*
00531  * Get the next entry. 
00532  *
00533  * @return value of the next element
00534  */
00535 //CPROPS_DLL 
00536 //void *cp_hashlist_get_next(cp_hashlist *list);
00537 
00538 /**
00539  * Test if object is empty.
00540  *
00541  * @retval true if no element contained.
00542  * @retval false if at least one element is contained.
00543  */
00544 CPROPS_DLL 
00545 int cp_hashlist_is_empty(cp_hashlist *list); //  { return cp_hashlist_item_count(list) == 0; }
00546 
00547 /**
00548  * Locks the collection with the specified mode.
00549  *
00550  * This overrides the default mode stored in the object.
00551  */
00552 CPROPS_DLL 
00553 int cp_hashlist_lock(cp_hashlist *list, int type);
00554 
00555 /**
00556  * Unlock the object.
00557  */
00558 CPROPS_DLL 
00559 int cp_hashlist_unlock(cp_hashlist *list);
00560 
00561 /**
00562  * Set a read lock on the object.
00563  */
00564 #define cp_hashlist_rdlock(list) cp_hashlist_lock((list), COLLECTION_LOCK_READ)
00565 
00566 /**
00567  * Set a write lock on the object.
00568  */
00569 #define cp_hashlist_wrlock(list) cp_hashlist_lock((list), COLLECTION_LOCK_WRITE)
00570 
00571 __END_DECLS
00572 
00573 /** @} */
00574 
00575 #endif
00576 

Generated on Fri Oct 22 2010 11:02:22 for SST by  doxygen 1.7.1