00001 /* priority_queue.h 00002 ** 00003 ** These are the defines and prototypes for a priority-sorted, 00004 ** stack-based queue of messages. 00005 ** 00006 ** CAUTION: RETURN CODES DIFFER SLIGHTLY FROM MEM_CIR_QUEUE AND 00007 ** SOME NON-ZERO RETURN CODES ARE NORMAL (see defs, below) 00008 ** 00009 ** CAUTION: THIS QUEUE TYPE MANAGES ITS OWN MUTEX FOR ACCESS CONTROL 00010 ** THERE IS NO NEED FOR THE CALLER TO DUPLICATE SUCH. 00011 ** 00012 ** 20020318 dbh - created 00013 */ 00014 00015 #ifndef PRIORITY_QUEUE_H 00016 #define PRIORITY_QUEUE_H 00017 00018 #include <transport.h> /* for MSG_LOGO */ 00019 00020 /* 00021 ** RETURN CODES 00022 */ 00023 #define EW_PRI_NOITEM 3 /* no item found in queue */ 00024 #define EW_PRI_RETREJECT 2 /* no space for this priority */ 00025 #define EW_PRI_RETDROP 1 /* earlier item dropped for space */ 00026 #define EW_PRI_RETNORMAL 0 /* normal */ 00027 #define EW_PRI_RETNOTREADY -1 /* queue not ready */ 00028 #define EW_PRI_RETMSGSIZE -2 /* message too large (or < 0) */ 00029 #define EW_PRI_RETQNULL -3 /* PRI_QUEUE pointer is NULL */ 00030 #define EW_PRI_RETMALLOC -4 /* memory allocation problem */ 00031 #define EW_PRI_RETBADPRI -5 /* invalid priority */ 00032 #define EW_PRI_RETPARAM -6 /* invalid parameter value */ 00033 00034 /* 00035 ** PRIORITY LEVELS 00036 ** 00037 ** CAUTION: Note that the highest priority (most important) 00038 ** items are assigned EW_PRIORITY_MIN. 00039 ** That is, these defines are for the programming 00040 ** domain, not the work domain. 00041 */ 00042 #define EW_PRIORITY_NONE 0 /* state when no message present */ 00043 #define EW_PRIORITY_MIN 1 /* the highest priority */ 00044 #define EW_PRIORITY_MAX 9 /* the lowest priority */ 00045 #define EW_PRIORITY_COUNT 10 /* simplifies loops */ 00046 00047 #define EW_PRIORITY_DEF 9 /* default priority => lowest work priority */ 00048 00049 00050 typedef short EW_PRIORITY; 00051 00052 00053 typedef char* PRI_DATA; 00054 00055 00056 typedef struct { 00057 EW_PRIORITY pri; 00058 MSG_LOGO logo; 00059 long length; 00060 PRI_DATA data; 00061 } PRI_QUEUE_ENTRY; 00062 00063 typedef struct 00064 { 00065 int queuesize; 00066 int itemsused; 00067 long itemmaxsize; 00068 int insert_indices[EW_PRIORITY_COUNT]; /* sort management */ 00069 PRI_QUEUE_ENTRY ** sorted; /* sorted pointers to objects */ 00070 PRI_QUEUE_ENTRY * entries; /* queue entries */ 00071 char * data; /* data storage */ 00072 mutex_t lock; 00073 } PRI_QUEUE; 00074 00075 00076 /********************************************************* 00077 ** init_pri_queue( PRI_QUEUE * p_queue 00078 ** , unsigned long p_max_items 00079 ** , unsigned long p_max_item_size ) 00080 ** 00081 ** Allocates and initializes all arrays and grabs a mutex 00082 ** for access control. 00083 ** 00084 ** parameters 00085 ** p_max_items: the maximum number of objects stored 00086 ** prior to dropping lower priorities. 00087 ** p_max_item_size: size to use for storage of items. 00088 ** 00089 ** returns: EW_PRI_RETNORMAL 00090 ** EW_PRI_RETQNULL 00091 ** EW_PRI_RETPARAM (p_max_items < 1) 00092 ** EW_PRI_RETMALLOC 00093 **********************************************************/ 00094 int init_pri_queue( PRI_QUEUE * p_queue 00095 , unsigned long p_max_items 00096 , unsigned long p_max_item_size ); 00097 00098 /********************************************************* 00099 ** release_pri_stack() releases allocated memory 00100 **********************************************************/ 00101 void release_pri_queue( PRI_QUEUE * p_queue ); 00102 00103 /********************************************************* 00104 ** getNumOfElementsInQueue() returns number of items in queue 00105 **********************************************************/ 00106 int getNumOfElementsInQueue( PRI_QUEUE * p_queue ); 00107 00108 /********************************************************* 00109 ** add_item( PRI_QUEUE * p_queue 00110 ** , EW_PRIORITY p_priority 00111 ** , MSG_LOGO p_logo 00112 ** , long p_size 00113 ** , DATA p_data ) 00114 ** 00115 ** Adds an object to the stack in priority order 00116 ** (The object is dropped if insufficient space available, 00117 ** item of lesser priority or of same priority but earlier 00118 ** may also be dropped to make space). 00119 ** 00120 ** parameters 00121 ** p_queue: PRI_QUEUE to act upon 00122 ** p_priority: Priority of the object 00123 ** p_logo: Message logo 00124 ** p_size: Length of message data 00125 ** p_data: Message data 00126 ** 00127 ** returns: EW_PRI_RETREJECT 00128 ** EW_PRI_RETDROP 00129 ** EW_PRI_RETNORMAL 00130 ** EW_PRI_RETNOTREADY 00131 ** EW_PRI_RETMSGSIZE 00132 ** EW_PRI_RETQNULL 00133 ** EW_PRI_RETBADPRI 00134 **********************************************************/ 00135 int add_item( PRI_QUEUE * p_queue 00136 , EW_PRIORITY p_priority 00137 , MSG_LOGO p_logo 00138 , long p_size 00139 , PRI_DATA p_data 00140 ); 00141 00142 /********************************************************* 00143 ** peek_next_item( PRI_QUEUE * p_queue 00144 ** , MSG_LOGO * p_logoptr ) 00145 ** , EW_PRIORITY * p_priptr ) 00146 ** 00147 ** Gets the highest available object currently stored on 00148 ** the stack. 00149 ** 00150 ** parameters 00151 ** p_queue: PRI_QUEUE to act upon 00152 ** p_logo: Pointer to Message logo to fill 00153 ** p_priptr: Pointer to EQ_PRIORITY to fill 00154 ** 00155 ** returns: EW_PRI_RETNORMAL (data ready) 00156 ** EW_PRI_RETNOTREADY 00157 ** EW_PRI_NOITEM (no item was in queue) 00158 ** EW_PRI_RETQNULL 00159 *********************************************************/ 00160 int peek_next_item( PRI_QUEUE * p_queue 00161 , MSG_LOGO * p_logoptr 00162 , EW_PRIORITY * p_priptr 00163 ); 00164 00165 /********************************************************* 00166 ** pop_next_item( PRI_QUEUE * p_queue 00167 ** , MSG_LOGO * p_logoptr 00168 ** , long * p_sizeptr 00169 ** , DATA p_data ) 00170 ** 00171 ** Gets the highest available object currently stored on 00172 ** the stack. 00173 ** 00174 ** parameters 00175 ** p_queue: PRI_QUEUE to act upon 00176 ** p_logo: Pointer to Message logo to fill 00177 ** p_size: Pointer to long to fill with message length 00178 ** p_data: Message data 00179 ** 00180 ** returns: EW_PRI_RETNORMAL (data ready) 00181 ** EW_PRI_RETNOTREADY 00182 ** EW_PRI_NOITEM (no item was in queue) 00183 ** EW_PRI_RETQNULL 00184 *********************************************************/ 00185 int pop_next_item( PRI_QUEUE * p_queue 00186 , MSG_LOGO * p_logoptr 00187 , long * p_sizeptr 00188 , PRI_DATA p_data 00189 ); 00190 00191 00192 #endif