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