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

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

Go to the documentation of this file.
00001 #ifndef _CP_PRIORITY_LIST_H
00002 #define _CP_PRIORITY_LIST_H
00003 
00004 /**
00005  * @addtogroup cp_priority_list
00006  */
00007 /** @{ */
00008 
00009 #include "common.h"
00010 
00011 __BEGIN_DECLS
00012 
00013 #include "config.h"
00014 
00015 #include "collection.h"
00016 #include "linked_list.h"
00017 
00018 #define PRIORITY_LIST_IMMEDIATE 1
00019 #define PRIORITY_LIST_NORMAL    2
00020 
00021 /**
00022  * @file
00023  * push your data on a cp_priority_list then retrieve them by priority. priority 
00024  * levels are 
00025  * 0 - immediate: a priority list instantiated with an immediate priority will 
00026  *     only return immediate priority items as long as such items are present
00027  *     on the immediate priority sub queue.
00028  * 1 - the first 'normal priority' subqueue defined. Subqueues are defined with 
00029  *     a weight. If you define the first subqueue with say weight 2 and the
00030  *     second with 1, in the absence of an immediate priority subqueue,
00031  *     calling cp_priority_list_get_next will return 2 items from the queue with
00032  *     weight 2, then 1 item from the queue with weight 1. Do not confuse the
00033  *     subqueue index, which is used to determine which queue you push items
00034  *     on (ie, what 'priority' they receive) with the actual weights. You
00035  *     could easily construct a cp_priority_list where priority 1 items have a
00036  *     lower weight than priority 2 items and vice versa. 
00037  * 
00038  */
00039 
00040 typedef CPROPS_DLL struct _cp_priority_list
00041 {
00042     cp_list *immediate;         /**< high priority queue for critical things */
00043     cp_list **normal;           /**< normal priority queues with precedence 
00044                                                                      weights */
00045     int *weight;                /**< table of weights for the normal queues */
00046     int normal_priority_queues; /**< number of normal priorities (supported 
00047                                                                      priority levels) */
00048     int distribution_counter;   /**<  */
00049     int cycle_position;         /**<  */
00050     int mode;                   /**< locking/operation mode */
00051         cp_thread txowner;                      /**< transaction lock owner */
00052         cp_compare_fn compare_fn;
00053 
00054     int item_count;             /**< number of elements in all queues */
00055 
00056     cp_lock *lock;                              /**< locking object */
00057         int txtype;                 /**< lock type */
00058 } cp_priority_list;
00059 
00060 
00061 /**
00062  * Internal destructor.
00063  */
00064 //void cp_priority_list_destroy_internal(cp_priority_list *list);
00065 
00066 /**
00067  * Simplified constructor.
00068  *
00069  * @param immediate     if true, create an immediate queue
00070  * @param normal_priority_queues
00071  * @param weights       table of weight factors
00072  */
00073 #define cp_priority_list_create(immediate, normal_priorities, weights) \
00074     cp_priority_list_create_by_option(immediate, normal_priorities, weights, \
00075                                                 NULL, NULL, NULL, COLLECTION_MODE_MULTIPLE_VALUES)
00076 
00077 /**
00078  * Constructor with all parameters.
00079  *
00080  * @param immediate             if true, create an immediate queue
00081  * @param normal_priorities     number of subqueues
00082  * @param weights               table of weight factors
00083  * @param compare_fn            compare method
00084  * @param copy_fn               copy method
00085  * @param mode                  operation and locking mode
00086  */
00087 CPROPS_DLL
00088 cp_priority_list *
00089         cp_priority_list_create_by_option(int immediate, 
00090                                                                           int normal_priority_queues, 
00091                                                                           int *weights, 
00092                                                                           cp_compare_fn compare_fn, 
00093                                                                           cp_copy_fn copy_fn, 
00094                                                                           cp_destructor_fn item_destructor,
00095                                                                           int mode);
00096 
00097 /**
00098  * Destructor
00099  */
00100 CPROPS_DLL
00101 void cp_priority_list_destroy(cp_priority_list *list);
00102 //#define cp_priority_list_destroy(list) cp_priority_list_destroy_by_option((list), (list)->mode)
00103 
00104 /**
00105  * Destructor with locking option.
00106  */
00107 CPROPS_DLL
00108 void cp_priority_list_destroy_by_option(cp_priority_list *list, int option);
00109 
00110 /**
00111  * Inserts an entry to the list with priority and default-mode.
00112  *
00113  * The entry is added to the list which holds the entries with given priority.
00114  * @param list the object
00115  * @param item the entry object
00116  * @param priority priority of the entry
00117  *
00118  * @note If the priority is out of supported range, the items are added to
00119  *       the queue with lowest priority .
00120  */
00121 CPROPS_DLL
00122 void *cp_priority_list_insert(cp_priority_list *list, void *item, int priority);
00123 
00124 /**
00125  * Inserts an entry to the list with priority and mode.
00126  *
00127  * The entry is added to the list which holds the entries with given priority.
00128  * @param list the object
00129  * @param item the entry object
00130  * @param priority priority of the entry
00131  * @param mode locking mode
00132  *
00133  * @note If the priority is out of supported range, the items are added to
00134  *       the queue with lowest priority .
00135  */
00136 CPROPS_DLL
00137 void *cp_priority_list_insert_by_option(cp_priority_list *list, void *item, int priority, int mode);
00138 
00139 /**
00140  * Get the "first" entry of the list with default-mode.
00141  *
00142  * The internal algorithm selects one of the non-empty list and 
00143  * returns the first entry of that list.
00144  */
00145 //void *cp_priority_list_get_next(cp_priority_list *list);
00146 #define cp_priority_list_get_next(l) cp_priority_list_get_next_by_option((l), (l)->mode)
00147 
00148 /**
00149  * Get the "first" entry of the list with mode.
00150  *
00151  * The internal algorithm selects one of the non-empty list and 
00152  * returns the first entry of that list.
00153  */
00154 CPROPS_DLL
00155 void *cp_priority_list_get_next_by_option(cp_priority_list *list, int mode);
00156 
00157 /**
00158  * Test if object is empty.
00159  *
00160  * @retval true if no element contained.
00161  * @retval false if at least one element is contained.
00162  */
00163 CPROPS_DLL
00164 int cp_priority_list_is_empty(cp_priority_list *list);
00165 
00166 
00167 /**
00168  * Lock the collection for reading.
00169  */
00170 #define cp_priority_list_rdlock(list) cp_priority_list_lock(list, COLLECTION_LOCK_READ)
00171 
00172 /**
00173  * Lock the collection for writing.
00174  */
00175 #define cp_priority_list_wrlock(list) cp_priority_list_lock(list, COLLECTION_LOCK_WRITE)
00176 
00177 /**
00178  * Lock the collection with mode.
00179  *
00180  * @param list the object
00181  * @param lock_mode locking mode
00182  */
00183 CPROPS_DLL
00184 int cp_priority_list_lock(cp_priority_list *list, int lock_mode);
00185 
00186 /**
00187  * Unlock the collection.
00188  */
00189 CPROPS_DLL
00190 int cp_priority_list_unlock(cp_priority_list *list);
00191 
00192 /**
00193  * Number of entries in the whole collection.
00194  *
00195  * @return number of entries.
00196  */
00197 CPROPS_DLL
00198 long cp_priority_list_item_count(cp_priority_list *list);
00199 
00200 __END_DECLS
00201 
00202 /** @} */
00203 #endif 
00204 

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