msgQ: CMK_USE_STL_MSGQ now causes converse to use an STL-based msgq
[charm.git] / src / conv-core / queueing.h
1 #ifndef QUEUEING_H
2 #define QUEUEING_H
3 /*#define FASTQ*/
4
5 /** 
6     @file 
7     Declarations of queuing data structure functions.
8     @ingroup CharmScheduler   
9
10     @addtogroup CharmScheduler
11     @{
12  */
13
14 #include "conv-config.h"
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20
21 /** A memory limit threshold for adaptively scheduling */
22 extern int schedAdaptMemThresholdMB;
23
24 #ifndef CINTBITS
25 #define CINTBITS ((unsigned int) (sizeof(int)*8))
26 #endif
27 #ifndef CLONGBITS
28 #define CLONGBITS ((unsigned int) (sizeof(CmiInt8)*8))
29 #endif
30
31 /** Stores a variable bit length priority */
32 typedef struct prio_struct
33 {
34   unsigned short bits;
35   unsigned short ints;
36   unsigned int data[1];
37 }
38 *_prio;
39
40 /**
41    A double ended queue of void* pointers stored in a circular buffer,
42    with internal space for 4 entries
43 */
44 typedef struct deq_struct
45 {
46   /* Note: if head==tail, circ is empty */
47   void **bgn; /**< Pointer to first slot in circular buffer */
48   void **end; /**< Pointer past last slot in circular buffer */
49   void **head; /**< Pointer to first used slot in circular buffer */
50   void **tail; /**< Pointer to next available slot in circular buffer */
51   void *space[4]; /**< Enough space for the first 4 entries */
52 }
53 *_deq;
54
55 #ifndef FASTQ
56 /**
57    A bucket in a priority queue which contains a deque(storing the
58    void* pointers) and references to other buckets in the hash
59    table.
60 */
61 typedef struct prioqelt_struct
62 {
63   struct deq_struct data;
64   struct prioqelt_struct *ht_next; /**< Pointer to next bucket in hash table. */
65   struct prioqelt_struct **ht_handle; /**< Pointer to pointer that points to me (!) */
66   struct prio_struct pri;
67 }
68 *_prioqelt;
69 #else
70 typedef struct prioqelt_struct
71 {
72   struct deq_struct data;
73   struct prioqelt_struct *ht_left; /**< Pointer to left bucket in hash table. */
74   struct prioqelt_struct *ht_right; /**< Pointer to right bucket in hash table. */
75   struct prioqelt_struct *ht_parent; /**< Pointer to the parent bucket in the hash table */
76   struct prioqelt_struct **ht_handle; /**< Pointer to pointer in the hashtable that points to me (!) */
77   struct prio_struct pri;
78   /*  int deleted; */
79 }
80 *_prioqelt;
81 #endif
82 /*
83 #ifndef FASTQ
84 #define PRIOQ_TABSIZE 1017
85 #else */
86 #define PRIOQ_TABSIZE 1017
87 /*#endif */
88
89 /*#ifndef FASTQ*/
90 /**
91    A priority queue, implemented as a heap of prioqelt_struct buckets
92    (each bucket represents a single priority value and contains a
93    deque of void* pointers)
94 */
95 typedef struct prioq_struct
96 {
97   int heapsize; 
98   int heapnext;
99   _prioqelt *heap; /**< An array of prioqelt's */
100   _prioqelt *hashtab;
101   int hash_key_size;
102   int hash_entry_size;
103 }
104 *_prioq;
105 /*#else
106 typedef struct prioq1_struct
107 {
108   int heapsize;
109   int heapnext;
110   prioqelt1 *heap;
111   prioqelt1 hashtab[PRIOQ_TABSIZE];
112 }
113 *prioq1;
114 #endif
115 */
116
117 /*#ifndef FASTQ*/
118 /**
119    A set of 3 queues: a positive priority prioq_struct, a negative
120    priority prioq_struct, and a zero priority deq_struct.
121    
122    If the user modifies the queue, NULL entries may be present, and
123    hence NULL values will be returned by CqsDequeue().
124 */
125 typedef struct Queue_struct
126 {
127   unsigned int length;
128   unsigned int maxlen;
129   struct deq_struct zeroprio; /**< A double ended queue for zero priority messages */
130   struct prioq_struct negprioq; /**< A priority queue for negative priority messages */
131   struct prioq_struct posprioq; /**< A priority queue for negative priority messages */
132 #if CMK_USE_STL_MSGQ
133   void *stlQ; /**< An STL-based alternative to charm's msg queues */
134 #endif
135 }
136 *Queue;
137 /*#else
138 typedef struct Queue1_struct
139 {
140   unsigned int length;
141   unsigned int maxlen;
142   struct deq_struct zeroprio;
143   struct prioq1_struct negprioq;
144   struct prioq1_struct posprioq;
145 }
146 *Queue;
147 #endif
148 */
149
150 /**
151     Initialize a Queue and its three internal queues (for positive,
152     negative, and zero priorities)
153 */
154 Queue CqsCreate(void);
155
156 /** Delete a Queue */
157 void CqsDelete(Queue);
158
159 /** Enqueue with priority 0 */
160 void CqsEnqueue(Queue, void *msg);
161
162 /** Enqueue behind other elements of priority 0 */
163 void CqsEnqueueFifo(Queue, void *msg);
164
165 /** Enqueue ahead of other elements of priority 0 */
166 void CqsEnqueueLifo(Queue, void *msg);
167
168 /**
169     Enqueue something (usually an envelope*) into the queue in a
170     manner consistent with the specified strategy and priority.
171 */
172 void CqsEnqueueGeneral(Queue, void *msg, int strategy, 
173                        int priobits, unsigned int *prioPtr);
174
175 /**
176     Produce an array containing all the entries in a Queue
177     @return a newly allocated array filled with copies of the (void*)
178     elements in the Queue.
179     @param [in] q a Queue
180     @param [out] resp an array of pointer entries found in the Queue,
181     with as many entries as the Queue's length. The caller must
182     CmiFree this.
183 */
184 void CqsEnumerateQueue(Queue q, void ***resp);
185
186 /**
187    Retrieve the highest priority message (one with most negative
188    priority)
189 */
190 void CqsDequeue(Queue, void **msgPtr);
191
192 unsigned int CqsLength(Queue);
193 int CqsEmpty(Queue);
194 int CqsPrioGT_(unsigned int ints1, unsigned int *data1, unsigned int ints2, unsigned int *data2);
195 int CqsPrioGT(_prio, _prio);
196
197 /** Get the priority of the highest priority message in q */
198 _prio CqsGetPriority(Queue);
199
200 void CqsIncreasePriorityForEntryMethod(Queue q, const int entrymethod);
201
202 /**
203     Remove an occurence of a specified entry from the Queue by setting
204     its entry to NULL.
205
206     The size of the Queue will not change, it will now just contain an
207     entry for a NULL pointer.
208 */
209 void CqsRemoveSpecific(Queue, const void *msgPtr);
210
211 #ifdef ADAPT_SCHED_MEM
212 void CqsIncreasePriorityForMemCriticalEntries(Queue q);
213 #endif
214
215 #ifdef __cplusplus
216 }
217 #endif
218
219 /** @} */
220
221 #endif