Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members  

priority_queue.h

Go to the documentation of this file.
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

Generated on Tue May 6 09:16:07 2003 for Earthworm Libs by doxygen1.3-rc3