76b4f436687d9a98518f56d220184ff337a42a3d
[charm.git] / src / ck-core / charm.h
1 /**
2 \file
3 \brief Charm Kernel--the groups and chares level of Charm++.
4 */
5 #ifndef CHARM_H
6 #define CHARM_H
7
8 #include "converse.h"
9 #include <sys/types.h> /* for size_t */
10
11 #ifdef __cplusplus
12 #include "pup.h"
13 extern "C" {
14 #endif
15
16
17 /******************************************************************************
18  *
19  * Converse Concepts, renamed to CK
20  *
21  *****************************************************************************/
22
23 /** Queueing types, for use with CkSetQueueing: */
24 #define CK_QUEUEING_FIFO   CQS_QUEUEING_FIFO
25 #define CK_QUEUEING_LIFO   CQS_QUEUEING_LIFO
26 #define CK_QUEUEING_IFIFO  CQS_QUEUEING_IFIFO
27 #define CK_QUEUEING_ILIFO  CQS_QUEUEING_ILIFO
28 #define CK_QUEUEING_BFIFO  CQS_QUEUEING_BFIFO
29 #define CK_QUEUEING_BLIFO  CQS_QUEUEING_BLIFO
30 #define CK_QUEUEING_LFIFO  CQS_QUEUEING_LFIFO
31 #define CK_QUEUEING_LLIFO  CQS_QUEUEING_LLIFO
32
33 #define CkTimer         CmiTimer
34 #define CkWallTimer     CmiWallTimer
35 #define CkCpuTimer      CmiCpuTimer
36
37 #define CkMyPe          CmiMyPe
38 #define CkMyRank        CmiMyRank
39 #define CkMyNode        CmiMyNode
40 #define CkNumPes        CmiNumPes
41 #define CkNumNodes      CmiNumNodes
42 #define CkNodeFirst     CmiNodeFirst
43 #define CkNodeSize      CmiNodeSize
44 #define CkMyNodeSize    CmiMyNodeSize
45 #define CkNodeOf        CmiNodeOf
46 #define CkRankOf        CmiRankOf
47
48 #define CkPrintf                CmiPrintf
49 #define CkScanf                 CmiScanf
50 #define CkError                 CmiError
51 #define CkAbort                 CmiAbort
52 #define CkAssert                CmiAssert
53
54 extern void  CkExit(void);
55 extern char **CkGetArgv(void);
56 extern int  CkGetArgc(void);
57
58 /******************************************************************************
59  *
60  * Miscellaneous Constants
61  *
62  *****************************************************************************/
63
64 #define CK_PE_ALL        CLD_BROADCAST_ALL
65 #define CK_PE_ALL_BUT_ME CLD_BROADCAST
66 #define CK_PE_ANY        CLD_ANYWHERE
67
68 /******************************************************************************
69  *
70  * Message Allocation Calls
71  *
72  *****************************************************************************/
73
74 extern void* CkAllocSysMsg(void);
75 extern void  CkFreeSysMsg(void *msg);
76 extern void* CkAllocMsg(int msgIdx, int msgBytes, int prioBits);
77 extern void* CkAllocBuffer(void *msg, int bufsize);
78 extern void  CkFreeMsg(void *msg);
79 extern void* CkCopyMsg(void **pMsg);
80 extern void  CkSetQueueing(void *msg, int strategy);
81 extern void* CkPriorityPtr(void *msg);
82
83 /*********************************************************/
84 /**
85 \addtogroup CkRegister
86 \brief Charm Registration--keeps track of the possible chare and method types.
87
88 These are implemented in register.C.
89 */
90 /*@{*/
91 /** Message pack function: convert a message into a buffer. */
92 typedef void* (*CkPackFnPtr)(void *msg);
93 /** Message unpack function: convert a buffer into a message. */
94 typedef void* (*CkUnpackFnPtr)(void *buf);
95 /** Message dealloc function: deletes a message. */
96 typedef void (*CkDeallocFnPtr)(void *msg);
97
98 /** Register this message name, with this basic size and pack and unpack functions. */
99 extern int CkRegisterMsg(const char *name, CkPackFnPtr pack, 
100                        CkUnpackFnPtr unpack, CkDeallocFnPtr dealloc, size_t size);
101
102 /** This entry point flag indicates the method does not keep the passed-in message. */
103 #define CK_EP_NOKEEP        (1<<2) 
104 #define CK_EP_INTRINSIC     (1<<3) 
105 #define CK_EP_TRACEDISABLE  (1<<4) 
106
107 #define CK_EP_MEMCRITICAL (1<<5)
108
109 /** type of a chare */
110 #if CMK_MESSAGE_LOGGING
111 typedef enum{
112         TypeInvalid=0,
113         TypeChare,
114         TypeMainChare,
115         TypeGroup,
116         TypeNodeGroup,
117         TypeArray,
118         TypeSection
119 } ChareType;
120 #else
121 typedef enum{
122         TypeInvalid=0,
123         TypeChare,
124         TypeMainChare,
125         TypeGroup,
126         TypeNodeGroup,
127         TypeArray
128 } ChareType;
129 #endif
130
131 /** A "call function" to invoke a method on an object. See EntryInfo */
132 typedef void  (*CkCallFnPtr) (void *msg, void *obj);
133 /** Register this entry point, with this call function and flags.
134     Returns the entry point's index in the _entryTable. */
135 extern int CkRegisterEp(const char *name, CkCallFnPtr call, int msgIdx, 
136                         int chareIdx,int ck_ep_flags);
137
138 /** Register this type of chare (group, or array), with this size.
139     Returns the Chare's index in the _chareTable. */
140 extern int CkRegisterChare(const char *name, size_t dataSz, ChareType chareType);
141 /** Register this chare as internal to Charm++.*/
142 extern void CkRegisterChareInCharm(int chareIndex);
143 /** Register this chare as a mainchare, with this entry point as its constructor.*/
144 extern int CkRegisterMainChare(int chareIndex, int epIndex);
145 /** Register a default constructor for this chare.*/
146 extern void CkRegisterDefaultCtor(int chareIndex, int ctorEpIndex);
147 /** Register a migration constructor for this chare.*/
148 extern void CkRegisterMigCtor(int chareIndex, int ctorEpIndex);
149 /** Indicate whether this group is an IrrGroup. */
150 extern void CkRegisterGroupIrr(int chareIndex,int isIrr);
151 /** Register the chare baseIdx as a base class of the chare derivedIdx. */
152 extern void CkRegisterBase(int derivedIdx, int baseIdx);
153
154 /** This function pup's a global variable.*/
155 typedef void (*CkPupReadonlyFnPtr)(void *pup_er);
156 /** Register this readonly global variable.*/
157 extern void CkRegisterReadonly(const char *name,const char *type,
158         int size, void *ptr,CkPupReadonlyFnPtr pup_fn);
159 /** Register this readonly message.*/
160 extern void CkRegisterReadonlyMsg(const char *name,const char *type,
161         void** pMsg);
162
163 /** A "marshall unpack" function: pups out parameters and calls a method. */
164 typedef int (*CkMarshallUnpackFn)(char *marshall_buf,void *object);
165 /** Register this marshall unpack function with this entry point.*/
166 extern void CkRegisterMarshallUnpackFn(int epIndex,CkMarshallUnpackFn m);
167 /** Lookup the marshall unpack function, if any, for this entry point.*/
168 extern CkMarshallUnpackFn CkLookupMarshallUnpackFn(int epIndex);
169
170 #ifdef __cplusplus
171 /** A "message pup" function: pups message data for debugger display. */
172 typedef void (*CkMessagePupFn)(PUP::er &p,void *userMessage);
173 /** Register this message pup function with this entry point.*/
174 extern void CkRegisterMessagePupFn(int epIndex,CkMessagePupFn m);
175 #endif
176 /*@}*/
177
178 /*********************************************************/
179 /**
180 \addtogroup Ck
181 \brief Charm Kernel--the groups and chares level of Charm++.
182
183 These routines are implemented in ck.C.
184 */
185 /*@{*/
186
187 typedef struct {
188   int   onPE;
189   void* objPtr;
190 } CkChareID;
191
192 typedef struct _ckGroupID{
193   int idx;              /* pe(processor number) is removed from the structure */
194 #ifdef __cplusplus
195   inline void pup(PUP::er &p) {  p|idx; }
196   inline int isZero(void) const { return (idx==0); }
197   inline void setZero(void) { idx=0; }
198   inline int operator==(const struct _ckGroupID& gid) const {
199     return (gid.idx==idx);
200   }
201   inline int operator<(const struct _ckGroupID& gid) const {
202     return (gid.idx<idx);
203   }
204 #endif
205 } CkGroupID;
206
207 typedef CkGroupID CkNodeGroupID;
208
209 /******************************************************************************
210  *
211  * Object Creation Calls
212  *
213  *****************************************************************************/
214 #ifdef __cplusplus
215 class envelope;
216 #else
217 typedef struct envelope envelope;
218 #endif
219 extern void CkCreateChare(int chareIdx, int constructorIdx, void *msg,
220                           CkChareID *vid, int destPE);
221 extern CkGroupID CkCreateGroup(int chareIdx, int constructorIdx, void *msg);
222 extern CkGroupID CkCreateNodeGroup(int chareIdx, int constructorIdx, void *msg);
223 extern void CkCreateLocalGroup(CkGroupID groupID, int constructorIdx, envelope *env);
224 extern void CkCreateLocalNodeGroup(CkGroupID groupID, int constructorIdx, envelope *env);
225
226
227
228 /******************************************************************************
229
230  This set of message type (mtype) constants
231  defines the basic class of charm++ message.
232  
233  It is very questionable whether bizarre stuff like
234  "ExitMsg", "StatMsg", "ROMsgMsg" should actually
235  share the envelope with regular user messages;
236  but it doesn't waste any space so it's probably OK.
237
238  These were formerly in envelope.h
239
240  *****************************************************************************/
241 /*** WARNING!!!! The following enum is linked to charmdebug finals in MsgInfo.java.
242  *   Make sure the two remain synchronized if changing this one.
243  ***/
244 typedef enum {
245   NewChareMsg    =1,
246   NewVChareMsg   =2,
247   BocInitMsg     =3,
248   ForChareMsg    =4,
249   ForBocMsg      =5,
250   ForVidMsg      =6,
251   FillVidMsg     =7,
252   DeleteVidMsg   =8,
253   RODataMsg      =9,
254   ROMsgMsg       =10,
255   StartExitMsg   =11,
256   ExitMsg        =12,
257   ReqStatMsg     =13,
258   StatMsg        =14,
259   NodeBocInitMsg =15,
260   ForNodeBocMsg  =16,
261   ArrayEltInitMsg =17,
262   ForArrayEltMsg  =18,
263   LAST_CK_ENVELOPE_TYPE =19
264 } CkEnvelopeType;
265
266
267
268 /******************************************************************************
269  *
270  * Asynchronous Remote Method Invocation Calls
271  *
272  *****************************************************************************/
273
274 #define CK_MSG_INLINE           0x1
275 #define CK_MSG_IMMEDIATE        0x2
276 #define CK_MSG_EXPEDITED        0x4
277 #define CK_MSG_KEEP             0x8    /* send without freeing message */
278 #define CK_MSG_LB_NOTRACE       0x10   /* load balancer doesn't trace */
279
280 #ifdef __cplusplus
281 #define CK_MSGOPTIONAL =0
282 #else
283 #define CK_MSGOPTIONAL
284 #endif
285
286 extern void CkSendMsg(int entryIndex, void *msg, const CkChareID *chare, int opts CK_MSGOPTIONAL);
287 extern void CkSendMsgBranch(int eIdx, void *msg, int destPE, CkGroupID gID, int opts CK_MSGOPTIONAL);
288 extern void CkSendMsgInline(int entryIndex, void *msg, const CkChareID *chare, int opts CK_MSGOPTIONAL);
289 extern void CkSendMsgBranchInline(int eIdx, void *msg, int destPE, CkGroupID gID, int opts CK_MSGOPTIONAL);
290 extern void CkSendMsgBranchMulti(int eIdx, void *msg, CkGroupID gID, int npes, int *pes, int opts CK_MSGOPTIONAL);
291 extern void CkSendMsgBranchGroup(int eIdx,void *msg,CkGroupID gID,CmiGroup grp, int opts CK_MSGOPTIONAL);
292 extern void CkSendMsgNodeBranch(int eIdx, void *msg, int destNode, CkGroupID gID, int opts CK_MSGOPTIONAL);
293 extern void CkSendMsgNodeBranchInline(int eIdx, void *msg, int destNode, CkGroupID gID, int opts CK_MSGOPTIONAL);
294 extern void CkSendMsgNodeBranchMulti(int eIdx, void *msg, CkGroupID gID, int npes, int *nodes, int opts CK_MSGOPTIONAL);
295 extern void CkBroadcastMsgBranch(int eIdx, void *msg, CkGroupID gID, int opts CK_MSGOPTIONAL);
296 extern void CkBroadcastMsgNodeBranch(int eIdx, void *msg, CkGroupID gID, int opts CK_MSGOPTIONAL);
297
298 extern int  CkChareMsgPrep(int eIdx, void *msg,const CkChareID *pCid);
299 extern void CkGroupMsgPrep(int eIdx, void *msg, CkGroupID gID);
300 extern void CkNodeGroupMsgPrep(int eIdx, void *msg, CkGroupID gID);
301
302 extern void CkSetRefNum(void *msg, CMK_REFNUM_TYPE ref);
303 extern CMK_REFNUM_TYPE  CkGetRefNum(void *msg);
304 extern int  CkGetSrcPe(void *msg);
305 extern int  CkGetSrcNode(void *msg);
306
307 extern void CkDeliverMessageFree(int epIdx,void *msg,void *object);
308 extern void CkDeliverMessageReadonly(int epIdx,const void *msg,void *object);
309
310 extern void *CkLocalBranch(CkGroupID gID);
311 extern void *CkLocalNodeBranch(CkGroupID gID);
312 extern void *CkLocalChare(const CkChareID *chare);
313
314 extern void CkArrayManagerInsert(int onPe,void *msg,CkGroupID aID);
315 extern void CkArrayManagerDeliver(int onPe,void *msg, int opts CK_MSGOPTIONAL);
316
317 /*@}*/
318
319
320
321 /******************************************************************************
322  *
323  * Semaphore calls
324  *
325  *****************************************************************************/
326
327 typedef struct _ckSemaID {
328   int pe;
329   int idx;
330 #ifdef __cplusplus
331   public:
332     void pup(PUP::er &p) { p(pe); p(idx); }
333 #endif
334 } CkSemaID;
335
336 extern CkSemaID CkSemaCreate(void);
337 extern void *CkSemaWait(CkSemaID id);
338 extern void CkSemaWaitN(CkSemaID id, int n, void *marray[]);
339 extern void CkSemaSignal(CkSemaID id, void *m);
340 extern void CkSemaDestroy(CkSemaID id);
341 /*@}*/
342
343
344 /******************************************************************************
345  *
346  * Quiescence Calls
347  *
348  *****************************************************************************/
349 /**
350 \addtogroup CkQD
351 \brief Quiescence Detection--a way to tell when nothing is happening.
352
353 These routines are implemented in qd.C and waitqd.C.
354 */
355 /*@{*/
356
357 /** When quiescence occurs, send a message to this entry point of this Chare. */
358 extern void CkStartQD(int eIdx,const CkChareID *chare);
359 /** Block until quiescence occurs. */
360 extern void CkWaitQD(void);
361 /*@}*/
362
363 /******************************************************************************
364  *
365  * Miscellaneous Calls
366  *
367  *****************************************************************************/
368
369 extern int CkMessageToEpIdx(void *msg);
370 extern void CkPrintEntryMethod(int epIdx);
371 extern void CkPrintChareName(int chareIdx);
372 extern void CkSummary_MarkEvent(int);
373 extern void CkSummary_StartPhase(int);
374 extern int CkDisableTracing(int epIdx);
375 extern void CkEnableTracing(int epIdx);
376
377 #ifdef __cplusplus
378 }
379 #endif
380 #endif