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

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

Go to the documentation of this file.
00001 #ifndef _CP_LINKEDLIST_H
00002 #define _CP_LINKEDLIST_H
00003 
00004 /** @{ */
00005 /**
00006  * @file
00007  *
00008  * linked list definitions
00009  */
00010 
00011 #include "common.h"
00012 
00013 __BEGIN_DECLS
00014 
00015 #include "config.h"
00016 #include "collection.h"
00017 #include "mempool.h"
00018 
00019 /**
00020  * Internal object that references the content and links to the neighbour
00021  * entries.
00022  */
00023 typedef CPROPS_DLL struct _cp_list_entry
00024 {
00025     void *item; /**< stored element (content) */
00026     struct _cp_list_entry *next; /**< link to next entry */
00027     struct _cp_list_entry *prev; /**< link to previous entry */
00028 } cp_list_entry;
00029 
00030 /**
00031  * doubly linked list type. 
00032  */
00033 typedef CPROPS_DLL struct _cp_list
00034 {
00035         cp_list_entry *head;            /**< link to beginning of list */
00036         cp_list_entry *tail;            /**< link to end of list       */
00037 
00038         cp_compare_fn compare_fn;       /**< comparison method             */
00039         cp_copy_fn copy_fn;             /**< copy method */
00040         cp_destructor_fn free_fn;       /**< item destructor */
00041 
00042         int mode;                       /**< operation mode (see collection.h) */
00043         cp_thread txowner;                      /**< current lock owner */
00044 
00045         long items;                     /**< number of elements in list */
00046 
00047         int is_view;                            /**< views don't have their own lock */
00048         cp_lock *lock;                          /**< lock */
00049         int txtype;                 /**< lock type */
00050 
00051         cp_mempool *mempool;            /**< optional memory pool */
00052 } cp_list;
00053 
00054 /**
00055  * iterator helper-class of cp_list.
00056  */
00057 typedef CPROPS_DLL struct _cp_list_iterator
00058 {
00059         cp_list *list;           /**< link to the list */
00060         cp_list_entry **pos;     /**< current position */
00061 
00062         int lock_type;           /**< locking mode */
00063 } cp_list_iterator;
00064 
00065 
00066 /** Default constructor */
00067 CPROPS_DLL 
00068 cp_list *cp_list_create();
00069 
00070 CPROPS_DLL 
00071 cp_list *cp_list_create_nosync();
00072 
00073 /**
00074  * Constructor
00075  *
00076  * @param mode operation mode bitmap (see collection.h)
00077  * @param compare_fn  compare method
00078  * @param copy_fn copy method
00079  */
00080 CPROPS_DLL 
00081 cp_list *cp_list_create_list(int mode, 
00082                                                          cp_compare_fn compare_fn, 
00083                                                          cp_copy_fn copy_fn, 
00084                                                          cp_destructor_fn item_destructor);
00085 
00086 CPROPS_DLL 
00087 cp_list *cp_list_create_view(int mode, 
00088                                                          cp_compare_fn compare_fn, 
00089                                                          cp_copy_fn copy_fn,
00090                                                          cp_destructor_fn item_destructor,
00091                                                          cp_lock *lock);
00092 
00093 /**
00094  * Destroy the object with the mode stored in the list.
00095  */
00096 CPROPS_DLL 
00097 void cp_list_destroy(cp_list *);
00098 
00099 /**
00100  * Destroy the object with the specified mode (override default).
00101  */
00102 CPROPS_DLL 
00103 void cp_list_destroy_by_option(cp_list *list, int option);
00104 
00105 /**
00106  * Destroy the object and all contained elements.
00107  * For each element the method cp_destructor_fn is called. 
00108  */
00109 CPROPS_DLL 
00110 void cp_list_destroy_custom(cp_list *list, cp_destructor_fn fn);
00111 
00112 /**
00113  * Insert a new element at the beginning of the list.
00114  * The operation is synchronized according to the properties of the object.
00115  */
00116 CPROPS_DLL 
00117 void *cp_list_insert(cp_list *list, void *item);
00118 
00119 /**
00120  * Remove the element from the list.
00121  * The operation is synchronized according to the properties of the object.
00122  */
00123 CPROPS_DLL 
00124 void *cp_list_remove(cp_list *list, void *item);
00125 
00126 /**
00127  * Insert the element after an existing one.
00128  */
00129 CPROPS_DLL 
00130 void *cp_list_insert_after(cp_list *list, void *item, void *existing);
00131 
00132 /**
00133  * Insert the element before an existing one.
00134  */
00135 CPROPS_DLL 
00136 void *cp_list_insert_before(cp_list *list, void *item, void *existing);
00137 
00138 /**
00139  * Get the first element that equals the parameter.
00140  */
00141 CPROPS_DLL 
00142 void *cp_list_search(cp_list *list, void *item);
00143 
00144 /**
00145  * run a callback on each item. Stops if the callback function returns
00146  * non-zero.
00147  */
00148 CPROPS_DLL 
00149 int cp_list_callback(cp_list *l, int (*item_action)(void *, void *), void *id);
00150 
00151 /**
00152  * Append the element at the end of the list.
00153  *
00154  * @retval item the appended item.
00155  * @retval existing_item if multiple values not allowed and an equal item already exists. 
00156  */
00157 CPROPS_DLL 
00158 void *cp_list_append(cp_list *list, void *item);
00159 
00160 /**
00161  * Returns the first element of the list.
00162  */
00163 CPROPS_DLL 
00164 void *cp_list_get_head(cp_list *list);
00165 
00166 /**
00167  * Returns the last element of the list.
00168  */
00169 CPROPS_DLL 
00170 void *cp_list_get_tail(cp_list *list);
00171 
00172 /**
00173  * remove and release first entry
00174  *
00175  * @return previous list head
00176  */
00177 CPROPS_DLL 
00178 void *cp_list_remove_head(cp_list *list);
00179 
00180 /**
00181  * remove and release last entry 
00182  *
00183  * @return Element that was stored in the last entry.
00184  */
00185 CPROPS_DLL 
00186 void *cp_list_remove_tail(cp_list *list);
00187 
00188 /**
00189  * Test if object is empty.
00190  *
00191  * @retval true if no element contained.
00192  * @retval false if at least one element is contained.
00193  */
00194 CPROPS_DLL 
00195 int cp_list_is_empty(cp_list *list);
00196 
00197 /**
00198  * Get the number of elements in the collection.
00199  * 
00200  * @return number of elements in the list.
00201  * @retval 0 if list is NULL
00202  */
00203 CPROPS_DLL 
00204 long cp_list_item_count(cp_list *);
00205 
00206 /**
00207  * Locks the collection with the specified mode.
00208  *
00209  * This overrides the default mode stored in the object.
00210  */
00211 CPROPS_DLL 
00212 int cp_list_lock(cp_list *list, int mode);
00213 
00214 /**
00215  * Set a read lock on the object.
00216  */
00217 #define cp_list_rdlock(list) cp_list_lock(list, COLLECTION_LOCK_READ)
00218 
00219 /**
00220  * Set a write lock on the object.
00221  */
00222 #define cp_list_wrlock(list) cp_list_lock(list, COLLECTION_LOCK_WRITE)
00223 
00224 /**
00225  * Unlock the object.
00226  */
00227 CPROPS_DLL 
00228 int cp_list_unlock(cp_list *list);
00229         
00230 /* set list to use given mempool or allocate a new one if pool is NULL */
00231 CPROPS_DLL
00232 int cp_list_use_mempool(cp_list *list, cp_mempool *pool);
00233 
00234 /* set list to use a shared memory pool */
00235 CPROPS_DLL
00236 int cp_list_share_mempool(cp_list *list, cp_shared_mempool *pool);
00237 
00238 
00239 /**
00240  * Initialize the Iterator at the first position.
00241  *
00242  * Set the iterator at the beginning of the list and lock the list in the
00243  * mode specified in type.
00244  *
00245  * @param iterator the iterator object
00246  * @param list the list to iterate over
00247  * @param lock_mode locking mode to use
00248  * @retval return-code of the aquired lock
00249  * @retval 0 if no locking
00250  */
00251 CPROPS_DLL 
00252 int cp_list_iterator_init(cp_list_iterator *iterator, cp_list *list, int lock_mode);
00253 
00254 /**
00255  * Initialize the Iterator at the end.
00256  *
00257  * Set the iterator at the end of the list and lock the list in the
00258  * mode specified in type.
00259  *
00260  * @param iterator the iterator object
00261  * @param list the list to iterate over
00262  * @param lock_mode locking mode to use
00263  * @retval return-code of the aquired lock
00264  * @retval 0 if no locking
00265  */
00266 CPROPS_DLL 
00267 int cp_list_iterator_init_tail(cp_list_iterator *iterator, cp_list *list, int lock_mode);
00268 
00269 /**
00270  * create a new iterator and initialize it at the beginning of the list.
00271  *
00272  * @param list the list to iterate over
00273  * @param lock_mode locking mode to use
00274  * @return new iterator object
00275  */
00276 CPROPS_DLL 
00277 cp_list_iterator* cp_list_create_iterator(cp_list *list, int lock_mode);
00278 
00279 /**
00280  * Move the iterator to the beginning of the list.
00281  */
00282 CPROPS_DLL 
00283 int cp_list_iterator_head(cp_list_iterator *iterator);
00284 
00285 /**
00286  * Move the iterator to the end of the list.
00287  */
00288 CPROPS_DLL 
00289 int cp_list_iterator_tail(cp_list_iterator *iterator);
00290 
00291 CPROPS_DLL 
00292 int cp_list_iterator_destroy(cp_list_iterator *iterator);
00293 
00294 /**
00295  * unlock the list the iterator is operating on.
00296  */
00297 CPROPS_DLL 
00298 int cp_list_iterator_release(cp_list_iterator *iterator);
00299 
00300 /**
00301  * Go to the next entry in the list and return the content.
00302  * 
00303  * @return object of the next entry.
00304  * @retval NULL if reading beyond end or from empty list.
00305  */
00306 CPROPS_DLL 
00307 void *cp_list_iterator_next(cp_list_iterator *iterator);
00308 
00309 /**
00310  * Go to the previous entry in the list and return the content.
00311  * 
00312  * @return object of the previous entry.
00313  * @retval NULL if reading beyond beginning or from empty list.
00314  */
00315 CPROPS_DLL 
00316 void *cp_list_iterator_prev(cp_list_iterator *iterator);
00317 
00318 /**
00319  * returns the value at the current iterator position
00320  * 
00321  * @return value at the current position.
00322  * @retval NULL if list is empty.
00323  */
00324 CPROPS_DLL 
00325 void *cp_list_iterator_curr(cp_list_iterator *iterator);
00326 
00327 
00328 /**
00329  * insert item to the list just before the current iterator position. In the 
00330  * special case that the iterator has been moved beyond the list end the new
00331  * item is added at the end of the list. 
00332  *
00333  * @return the added item or NULL if the list mode is not 
00334  *                 & COLLECTION_MODE_NOSYNC and the iterator does not own a write lock
00335  */
00336 CPROPS_DLL 
00337 void *cp_list_iterator_insert(cp_list_iterator *iterator, void *item);
00338 
00339 /**
00340  * append item to the list just after the current iterator position. In the 
00341  * special case that the iterator has been moved beyond the list head the new
00342  * item is added at the head of the list. 
00343  *
00344  * @return the added item or NULL if the list mode is not 
00345  *                 & COLLECTION_MODE_NOSYNC and the iterator does not own a write lock
00346  */
00347 CPROPS_DLL 
00348 void *cp_list_iterator_append(cp_list_iterator *iterator, void *item);
00349 
00350 /**
00351  * delete the item at the current iterator position.
00352  *
00353  * @return the deleted item or NULL the list is empty, if the iterator points
00354  *                 beyond list limits or if the list mode is not 
00355  *                 & COLLECTION_MODE_NOSYNC and the iterator does not own a write lock
00356  */
00357 CPROPS_DLL 
00358 void *cp_list_iterator_remove(cp_list_iterator *iterator);
00359 
00360 __END_DECLS
00361 
00362 /** @} */
00363 
00364 #endif

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