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