Improving documentation for scheduling routines.
[charm.git] / src / conv-core / queueing.h
1 /*****************************************************************************
2  * $Source$
3  * $Author$
4  * $Date$
5  * $Revision$
6  *****************************************************************************/
7
8 #ifndef QUEUEING_H
9 #define QUEUEING_H
10 /*#define FASTQ*/
11
12
13 /** 
14     @file 
15     Declarations of queuing data structure functions.
16     @ingroup CharmScheduler   
17
18     @addtogroup CharmScheduler
19     @{
20  */
21
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27
28 /** A memory limit threshold for adaptively scheduling */
29 extern int schedAdaptMemThresholdMB;
30
31 #ifndef CINTBITS
32 #define CINTBITS ((unsigned int) (sizeof(int)*8))
33 #endif
34 #ifndef CLONGBITS
35 #define CLONGBITS ((unsigned int) (sizeof(CmiInt8)*8))
36 #endif
37
38 /** Stores a variable bit length priority */
39 typedef struct prio_struct
40 {
41   unsigned short bits;
42   unsigned short ints;
43   unsigned int data[1];
44 }
45 *prio;
46
47 /** A double ended queue of void* pointers stored in a circular buffer, with internal space for 4 entries */
48 typedef struct deq_struct
49 {
50   /* Note: if head==tail, circ is empty */
51   void **bgn; /**< Pointer to first slot in circular buffer */
52   void **end; /**< Pointer past last slot in circular buffer */
53   void **head; /**< Pointer to first used slot in circular buffer */
54   void **tail; /**< Pointer to next available slot in circular buffer */
55   void *space[4]; /**< Enough space for the first 4 entries */
56 }
57 *deq;
58
59 #ifndef FASTQ
60 /** An bucket in a priority queue which contains a deque(storing the void* pointers) and references to other buckets in the hash table. */
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 /** A priority queue, implemented as a heap of prioqelt_struct buckets (each bucket represents a single priority value and contains a deque of void* pointers) */
91 typedef struct prioq_struct
92 {
93   int heapsize; 
94   int heapnext;
95   prioqelt *heap; /**< An array of prioqelt's */
96   prioqelt *hashtab;
97   int hash_key_size;
98   int hash_entry_size;
99 }
100 *prioq;
101 /*#else
102 typedef struct prioq1_struct
103 {
104   int heapsize;
105   int heapnext;
106   prioqelt1 *heap;
107   prioqelt1 hashtab[PRIOQ_TABSIZE];
108 }
109 *prioq1;
110 #endif
111 */
112
113 /*#ifndef FASTQ*/
114 /** A set of 3 queues: a positive priority prioq_struct, a negative priority prioq_struct, and a zero priority deq_struct.
115     If the user modifies the queue, NULL entries may be present, and hence NULL values will be returned by CqsDequeue().
116 */
117 typedef struct Queue_struct
118 {
119   unsigned int length;
120   unsigned int maxlen;
121   struct deq_struct zeroprio; /**< A double ended queue for zero priority messages */
122   struct prioq_struct negprioq; /**< A priority queue for negative priority messages */
123   struct prioq_struct posprioq; /**< A priority queue for negative priority messages */
124 }
125 *Queue;
126 /*#else
127 typedef struct Queue1_struct
128 {
129   unsigned int length;
130   unsigned int maxlen;
131   struct deq_struct zeroprio;
132   struct prioq1_struct negprioq;
133   struct prioq1_struct posprioq;
134 }
135 *Queue;
136 #endif
137 */
138
139 Queue CqsCreate(void);
140 void CqsDelete(Queue);
141 void CqsEnqueue(Queue, void *msg);
142 void CqsEnqueueFifo(Queue, void *msg);
143 void CqsEnqueueLifo(Queue, void *msg);
144 void CqsEnqueueGeneral(Queue, void *msg,int strategy, 
145                int priobits, unsigned int *prioPtr);
146
147 void CqsEnumerateQueue(Queue q, void ***resp);
148 void CqsDequeue(Queue, void **msgPtr);
149
150 unsigned int CqsLength(Queue);
151 unsigned int CqsMaxLength(Queue);
152 int CqsEmpty(Queue);
153 int CqsPrioGT(prio, prio);
154 prio CqsGetPriority(Queue);
155
156 deq CqsPrioqGetDeq(prioq pq, unsigned int priobits, unsigned int *priodata);
157 void *CqsPrioqDequeue(prioq pq);
158 void CqsDeqEnqueueFifo(deq d, void *data);
159
160 void CqsIncreasePriorityForEntryMethod(Queue q, const int entrymethod);
161 void CqsRemoveSpecific(Queue, const void *msgPtr);
162
163
164 #ifdef __cplusplus
165 };
166 #endif
167
168 /** @} */
169
170 #endif