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