Charm++: Charm Source Code Documentation

00001 
00005 #ifndef CHARM_H
00006 #define CHARM_H
00007 
00008 #include "converse.h"
00009 #include <sys/types.h> /* for size_t */
00010 
00011 #ifdef __cplusplus
00012 #include "pup.h"
00013 extern "C" {
00014 #endif
00015 
00016 
00017 /******************************************************************************
00018  *
00019  * Converse Concepts, renamed to CK
00020  *
00021  *****************************************************************************/
00022 
00024 #define CK_QUEUEING_FIFO   CQS_QUEUEING_FIFO
00025 #define CK_QUEUEING_LIFO   CQS_QUEUEING_LIFO
00026 #define CK_QUEUEING_IFIFO  CQS_QUEUEING_IFIFO
00027 #define CK_QUEUEING_ILIFO  CQS_QUEUEING_ILIFO
00028 #define CK_QUEUEING_BFIFO  CQS_QUEUEING_BFIFO
00029 #define CK_QUEUEING_BLIFO  CQS_QUEUEING_BLIFO
00030 #define CK_QUEUEING_LFIFO  CQS_QUEUEING_LFIFO
00031 #define CK_QUEUEING_LLIFO  CQS_QUEUEING_LLIFO
00032 
00033 #define CkTimer     CmiTimer
00034 #define CkWallTimer     CmiWallTimer
00035 #define CkCpuTimer      CmiCpuTimer
00036 
00037 #define CkMyPe          CmiMyPe
00038 #define CkMyRank        CmiMyRank
00039 #define CkMyNode        CmiMyNode
00040 #define CkNumPes        CmiNumPes
00041 #define CkNumNodes      CmiNumNodes
00042 #define CkNumPhysicalNodes  CmiNumPhysicalNodes
00043 #define CkNodeFirst     CmiNodeFirst
00044 #define CkNodeSize      CmiNodeSize
00045 #define CkMyNodeSize        CmiMyNodeSize
00046 #define CkNodeOf        CmiNodeOf
00047 #define CkRankOf        CmiRankOf
00048 
00049 #define CkPrintf                CmiPrintf
00050 #define CkScanf                 CmiScanf
00051 #define CkError                 CmiError
00052 #define CkAbort                 CmiAbort
00053 #define CkAssert                CmiAssert
00054 #define CkSetPeHelpsOtherThreads CmiSetPeHelpsOtherThreads
00055 
00056 void realCkExit(int exitcode);
00057 
00058 /* Optional parameter for CkExit() - based on
00059 https://stackoverflow.com/a/28074198/1250282 */
00060 
00061 #define CKEXIT_1(x) realCkExit(x)
00062 #define CKEXIT_0() CKEXIT_1(0) /* Default CkExit() exit code: 0 */
00063 
00064 #define CKEXIT_FUNC_CHOOSER(_f1, _f2, _f3, ...) _f3
00065 #define CKEXIT_FUNC_RECOMPOSER(argsWithParentheses) CKEXIT_FUNC_CHOOSER argsWithParentheses
00066 #define CKEXIT_CHOOSE_FROM_ARG_COUNT(...) CKEXIT_FUNC_RECOMPOSER((__VA_ARGS__, CKEXIT_2, CKEXIT_1, ))
00067 #define CKEXIT_NO_ARG_EXPANDER() ,,CKEXIT_0
00068 #define CKEXIT_MACRO_CHOOSER(...) CKEXIT_CHOOSE_FROM_ARG_COUNT(CKEXIT_NO_ARG_EXPANDER __VA_ARGS__ ())
00069 #define CkExit(...) CKEXIT_MACRO_CHOOSER(__VA_ARGS__)(__VA_ARGS__)
00070 
00071 
00072 #if CMK_SHRINK_EXPAND
00073 extern void  CkCleanup(void);
00074 #endif
00075 extern char **CkGetArgv(void);
00076 extern int  CkGetArgc(void);
00077 
00078 /******************************************************************************
00079  *
00080  * Miscellaneous Constants
00081  *
00082  *****************************************************************************/
00083 
00084 #define CK_PE_ALL        CLD_BROADCAST_ALL
00085 #define CK_PE_ALL_BUT_ME CLD_BROADCAST
00086 #define CK_PE_ANY        CLD_ANYWHERE
00087 
00088 /******************************************************************************
00089  *
00090  * Message Allocation Calls
00091  *
00092  *****************************************************************************/
00093 #ifdef __cplusplus
00094 class CkEntryOptions;
00095 extern void* CkAllocSysMsg(const CkEntryOptions *opts = NULL);
00096 #ifndef GROUPDEPNUM_DECLARED
00097 # define GROUPDEPNUM_DECLARED
00098 struct GroupDepNum
00099 {
00100   int groupDepNum;
00101   explicit GroupDepNum(int g = 0) : groupDepNum{g} { }
00102   operator int() const { return groupDepNum; }
00103 };
00104 #endif
00105 extern void* CkAllocMsg(int msgIdx, int msgBytes, int prioBits, GroupDepNum groupDepNum=GroupDepNum{});
00106 #endif
00107 extern void  CkFreeSysMsg(void *msg);
00108 extern void* CkAllocBuffer(void *msg, int bufsize);
00109 extern void  CkFreeMsg(void *msg);
00110 extern void* CkCopyMsg(void **pMsg);
00111 extern void  CkSetQueueing(void *msg, int strategy);
00112 extern void* CkPriorityPtr(void *msg);
00113 
00114 /******************************************************************************
00115  *
00116  * Functions be to called from external clients (e.g. Charm4py)
00117  *
00118  *****************************************************************************/
00119 
00120 extern void registerCkRegisterMainModuleCallback(void (*cb)(void));
00121 extern void registerMainchareCtorExtCallback(void (*cb)(int, void*, int, int, char **));
00122 extern void registerReadOnlyRecvExtCallback(void (*cb)(int, char*));
00123 extern void registerChareMsgRecvExtCallback(void (*cb)(int, void*, int, int, char*, int));
00124 extern void registerGroupMsgRecvExtCallback(void (*cb)(int, int, int, char *, int));
00125 extern void registerArrayMsgRecvExtCallback(void (*cb)(int, int, int *, int, int, char *, int));
00126 extern void registerArrayElemLeaveExtCallback(int (*cb)(int, int, int *, char**, int));
00127 extern void registerArrayElemJoinExtCallback(void (*cb)(int, int, int *, int, char*, int));
00128 extern void registerArrayResumeFromSyncExtCallback(void (*cb)(int, int, int *));
00129 extern void registerArrayMapProcNumExtCallback(int (*cb)(int, int, const int *));
00130 extern void StartCharmExt(int argc, char **argv); // start Converse/Charm, argv are the command-line arguments
00131 extern int CkMyPeHook(void);   // function equivalent of CkMyPe macro
00132 extern int CkNumPesHook(void); // function equivalent of CkNumPes macro
00134 extern int CkGroupGetReductionNumber(int gid);
00136 extern int CkArrayGetReductionNumber(int aid, int ndims, int *index);
00137 extern void registerCreateReductionTargetMsgExtCallback(void (*cb)(void*, int, int, int, char**, int*));
00138 extern void registerPyReductionExtCallback(int (*cb)(char**, int*, int, char**));
00139 
00140 /*********************************************************/
00149 typedef void* (*CkPackFnPtr)(void *msg);
00151 typedef void* (*CkUnpackFnPtr)(void *buf);
00153 typedef void (*CkDeallocFnPtr)(void *msg);
00154 
00156 extern int CkRegisterMsg(const char *name, CkPackFnPtr pack, 
00157                        CkUnpackFnPtr unpack, CkDeallocFnPtr dealloc, size_t size);
00158 
00160 #define CK_EP_NOKEEP        (1<<2) 
00161 #define CK_EP_INTRINSIC     (1<<3) 
00162 #define CK_EP_TRACEDISABLE  (1<<4) 
00163 
00164 #define CK_EP_MEMCRITICAL (1<<5)
00165 #define CK_EP_APPWORK     (1<<6)
00166 #define CK_EP_IMMEDIATE   (1<<7)
00167 #define CK_EP_INLINE      (1<<8)
00168 
00170 #if CMK_MESSAGE_LOGGING
00171 typedef enum{
00172     TypeInvalid=0,
00173     TypeChare,
00174     TypeMainChare,
00175     TypeGroup,
00176     TypeNodeGroup,
00177     TypeArray,
00178     TypeSection
00179 } ChareType;
00180 #else
00181 typedef enum{
00182     TypeInvalid=0,
00183     TypeChare,
00184     TypeMainChare,
00185     TypeGroup,
00186     TypeNodeGroup,
00187     TypeArray
00188 } ChareType;
00189 #endif
00190 
00192 typedef void  (*CkCallFnPtr) (void *msg, void *obj);
00195 extern int CkRegisterEp(const char *name, CkCallFnPtr call, int msgIdx,
00196                         int chareIdx, int ck_ep_flags);
00197 extern int CkRegisterEpTemplated(const char *name, CkCallFnPtr call, int msgIdx,
00198                                  int chareIdx, int ck_ep_flags);
00199 
00202 extern int CkRegisterChare(const char *name, size_t dataSz, ChareType chareType);
00204 extern void CkRegisterArrayDimensions(int chareIndex, int ndims);
00206 extern void CkRegisterChareInCharm(int chareIndex);
00208 extern int CkRegisterMainChare(int chareIndex, int epIndex);
00209 extern void CkRegisterMainChareExt(const char *s, int numEntryMethods, int *chareIdx, int *startEpIdx);
00211 extern void CkRegisterDefaultCtor(int chareIndex, int ctorEpIndex);
00213 extern void CkRegisterMigCtor(int chareIndex, int ctorEpIndex);
00215 extern void CkRegisterGroupIrr(int chareIndex,int isIrr);
00216 extern void CkRegisterGroupExt(const char *s, int numEntryMethods, int *chareIdx, int *startEpIdx);
00217 extern void CkRegisterArrayMapExt(const char *s, int numEntryMethods, int *chareIdx, int *startEpIdx);
00218 extern void CkRegisterArrayExt(const char *s, int numEntryMethods, int *chareIdx, int *startEpIdx);
00220 extern void CkRegisterBase(int derivedIdx, int baseIdx);
00221 
00223 typedef void (*CkPupReadonlyFnPtr)(void *pup_er);
00225 extern void CkRegisterReadonly(const char *name,const char *type,
00226     size_t size, void *ptr,CkPupReadonlyFnPtr pup_fn);
00227 extern void CkRegisterReadonlyExt(const char *name, const char *type, size_t msgSize, char *msg);
00229 extern void CkRegisterReadonlyMsg(const char *name,const char *type,
00230     void** pMsg);
00231 
00233 typedef int (*CkMarshallUnpackFn)(char *marshall_buf,void *object);
00235 extern void CkRegisterMarshallUnpackFn(int epIndex,CkMarshallUnpackFn m);
00237 extern CkMarshallUnpackFn CkLookupMarshallUnpackFn(int epIndex);
00238 
00239 #ifdef __cplusplus
00240 
00241 typedef void (*CkMessagePupFn)(PUP::er &p,void *userMessage);
00243 extern void CkRegisterMessagePupFn(int epIndex,CkMessagePupFn m);
00244 #endif
00245 
00247 /*********************************************************/
00255 
00256 typedef struct {
00257   int   onPE;
00258   void* objPtr;
00259 } CkChareID;
00260 
00261 typedef struct _ckGroupID{
00262   int idx;      /* pe(processor number) is removed from the structure */
00263 #ifdef __cplusplus
00264   inline void pup(PUP::er &p) {  p|idx; }
00265   inline bool isZero(void) const { return (idx==0); }
00266   inline void setZero(void) { idx=0; }
00267   inline int operator==(const struct _ckGroupID& gid) const {
00268     return (gid.idx==idx);
00269   }
00270   inline int operator<(const struct _ckGroupID& gid) const {
00271     return (gid.idx<idx);
00272   }
00273 #endif
00274 } CkGroupID;
00275 
00276 typedef CkGroupID CkNodeGroupID;
00277 
00278 /******************************************************************************
00279  *
00280  * Object Creation Calls
00281  *
00282  *****************************************************************************/
00283 #ifdef __cplusplus
00284 class envelope;
00285 #else
00286 typedef struct envelope envelope;
00287 #endif
00288 extern void CkCreateChare(int chareIdx, int constructorIdx, void *msg,
00289                           CkChareID *vid, int destPE);
00290 extern CkGroupID CkCreateGroup(int chareIdx, int constructorIdx, void *msg);
00291 extern CkGroupID CkCreateNodeGroup(int chareIdx, int constructorIdx, void *msg);
00292 extern void CkCreateLocalGroup(CkGroupID groupID, int constructorIdx, envelope *env);
00293 extern void CkCreateLocalNodeGroup(CkGroupID groupID, int constructorIdx, envelope *env);
00294 
00295 extern int CkCreateGroupExt(int cIdx, int eIdx, int num_bufs, char **bufs, int *buf_sizes);
00296 extern int CkCreateArrayExt(int cIdx, int ndims, int *dims, int eIdx, int num_bufs, char **bufs, int *buf_sizes, int map_gid, char useAtSync);
00297 extern void CkInsertArrayExt(int aid, int ndims, int *index, int epIdx, int onPE, int num_bufs, char **bufs, int *buf_sizes, char useAtSync);
00298 extern void CkArrayDoneInsertingExt(int aid);
00299 extern void CkMigrateExt(int aid, int ndims, int *index, int toPe);
00300 
00301 
00302 /******************************************************************************
00303 
00304  This set of message type (mtype) constants
00305  defines the basic class of charm++ message.
00306  
00307  It is very questionable whether bizarre stuff like
00308  "ExitMsg", "StatMsg", "ROMsgMsg" should actually
00309  share the envelope with regular user messages;
00310  but it doesn't waste any space so it's probably OK.
00311 
00312  These were formerly in envelope.h
00313 
00314  *****************************************************************************/
00315 /*** WARNING!!!! The following enum is linked to charmdebug finals in MsgInfo.java.
00316  *   Make sure the two remain synchronized if changing this one.
00317  ***/
00318 typedef enum {
00319   NewChareMsg          =1,               // Singleton chare creation message
00320   NewVChareMsg         =2,               // Singleton virtual chare creation message
00321   BocInitMsg           =3,               // Group creation message
00322   ForChareMsg          =4,               // Singleton chare entry method message (non creation)
00323   ForBocMsg            =5,               // Group entry method message (non creation)
00324   ForVidMsg            =6,               // Singleton virtual chare entry method message (non creation)
00325   FillVidMsg           =7,               // Message sent to fill a VidBlock on a virtual chare PE
00326   DeleteVidMsg         =8,               // Message sent to delete a VidBlock on a virtual chare PE
00327   RODataMsg            =9,               // Readonly Data Message (for user declared readonly variables)
00328   ROMsgMsg             =10,              // Readonly message Message (for user declared readonly messages)
00329   ROPeerCompletionMsg  =11,              // Message to signal completion of RO Data transfer using Zcpy API
00330                                          // ^(used by child nodes to signal completion to their parent node in the bcast spanning tree)
00331   ROChildCompletionMsg =12,              // Message to signal completion of RO Data transfer using Zcpy API
00332                                          // ^(used by peer nodes to signal completion to the 0th node)
00333   StartExitMsg         =13,              // Exit sequence trigger message
00334   ExitMsg              =14,              // Exit sequence trigger message using user registered exit function
00335   ReqStatMsg           =15,              // Request stats and warnings message
00336   StatMsg              =16,              // Stats data message (Reduction)
00337   StatDoneMsg          =17,              // Signal completion of stats reduction (Broadcast)
00338   NodeBocInitMsg       =18,              // Nodegroup creation message
00339   ForNodeBocMsg        =19,              // Nodegroup entry method message (non creation)
00340   ArrayEltInitMsg      =20,              // Array Element Initialization message
00341   ForArrayEltMsg       =21,              // Array Element entry method message
00342   ForIDedObjMsg        =22,
00343 #if CMK_LOCKLESS_QUEUE
00344   WarnMsg              =23,              // Warning data message (Reduction)
00345   WarnDoneMsg          =24,              // Signal completion of warnings reduction (Broadcast)
00346   LAST_CK_ENVELOPE_TYPE =25              // Used for error-checking
00347 #else
00348   LAST_CK_ENVELOPE_TYPE =23              // Used for error-checking
00349 #endif
00350 } CkEnvelopeType;
00351 
00352 
00353 
00354 /******************************************************************************
00355  *
00356  * Asynchronous Remote Method Invocation Calls
00357  *
00358  *****************************************************************************/
00359 
00360 #define CK_MSG_INLINE       0x1
00361 #define CK_MSG_IMMEDIATE    0x2
00362 #define CK_MSG_EXPEDITED    0x4
00363 #define CK_MSG_KEEP     0x8    /* send without freeing message */
00364 #define CK_MSG_LB_NOTRACE   0x10   /* load balancer doesn't trace */
00365 
00366 #ifdef __cplusplus
00367 #define CK_MSGOPTIONAL =0
00368 #else
00369 #define CK_MSGOPTIONAL
00370 #endif
00371 
00372 extern void CkSendMsg(int entryIndex, void *msg, const CkChareID *chare, int opts CK_MSGOPTIONAL);
00373 extern void CkSendMsgBranch(int eIdx, void *msg, int destPE, CkGroupID gID, int opts CK_MSGOPTIONAL);
00374 extern void CkSendMsgInline(int entryIndex, void *msg, const CkChareID *chare, int opts CK_MSGOPTIONAL);
00375 extern void CkSendMsgBranchInline(int eIdx, void *msg, int destPE, CkGroupID gID, int opts CK_MSGOPTIONAL);
00376 extern void CkSendMsgBranchMulti(int eIdx, void *msg, CkGroupID gID, int npes, const int *pes, int opts CK_MSGOPTIONAL);
00377 extern void CkSendMsgBranchGroup(int eIdx,void *msg,CkGroupID gID,CmiGroup grp, int opts CK_MSGOPTIONAL);
00378 extern void CkSendMsgNodeBranch(int eIdx, void *msg, int destNode, CkGroupID gID, int opts CK_MSGOPTIONAL);
00379 extern void CkSendMsgNodeBranchInline(int eIdx, void *msg, int destNode, CkGroupID gID, int opts CK_MSGOPTIONAL);
00380 extern void CkSendMsgNodeBranchMulti(int eIdx, void *msg, CkGroupID gID, int npes, const int *nodes, int opts CK_MSGOPTIONAL);
00381 extern void CkBroadcastMsgBranch(int eIdx, void *msg, CkGroupID gID, int opts CK_MSGOPTIONAL);
00382 extern void CkBroadcastMsgNodeBranch(int eIdx, void *msg, CkGroupID gID, int opts CK_MSGOPTIONAL);
00383 
00384 extern int  CkChareMsgPrep(int eIdx, void *msg,const CkChareID *pCid);
00385 extern void CkGroupMsgPrep(int eIdx, void *msg, CkGroupID gID);
00386 extern void CkNodeGroupMsgPrep(int eIdx, void *msg, CkGroupID gID);
00387 
00388 extern void CkSetRefNum(void *msg, CMK_REFNUM_TYPE ref);
00389 extern CMK_REFNUM_TYPE  CkGetRefNum(void *msg);
00390 extern int  CkGetSrcPe(void *msg);
00391 extern int  CkGetSrcNode(void *msg);
00392 
00393 extern void CkDeliverMessageFree(int epIdx,void *msg,void *object);
00394 extern void CkDeliverMessageReadonly(int epIdx,const void *msg,void *object);
00395 
00396 extern void *CkLocalBranch(CkGroupID gID);
00397 extern void *CkLocalNodeBranch(CkGroupID gID);
00398 extern void *CkLocalChare(const CkChareID *chare);
00399 
00400 extern void CkArrayManagerDeliver(int onPe,void *msg, int opts CK_MSGOPTIONAL);
00401 
00403 extern void CkChareExtSend(int onPE, void *objPtr, int epIdx, char *msg, int msgSize);
00405 extern void CkChareExtSend_multi(int onPE, void *objPtr, int epIdx, int num_bufs, char **bufs, int *buf_sizes);
00408 extern void CkGroupExtSend(int gid, int pe, int epIdx, char *msg, int msgSize);
00410 extern void CkGroupExtSend_multi(int gid, int pe, int epIdx, int num_bufs, char **bufs, int *buf_sizes);
00413 extern void CkArrayExtSend(int aid, int *idx, int ndims, int epIdx, char *msg, int msgSize);
00415 extern void CkArrayExtSend_multi(int aid, int *idx, int ndims, int epIdx, int num_bufs, char **bufs, int *buf_sizes);
00416 
00421 /******************************************************************************
00422  *
00423  * Semaphore calls
00424  *
00425  *****************************************************************************/
00426 
00427 typedef struct _ckSemaID {
00428   int pe;
00429   int idx;
00430 #ifdef __cplusplus
00431   public:
00432     void pup(PUP::er &p) { p(pe); p(idx); }
00433 #endif
00434 } CkSemaID;
00435 
00436 extern CkSemaID CkSemaCreate(void);
00437 extern void *CkSemaWait(CkSemaID id);
00438 extern void CkSemaWaitN(CkSemaID id, int n, void *marray[]);
00439 extern void CkSemaSignal(CkSemaID id, void *m);
00440 extern void CkSemaDestroy(CkSemaID id);
00444 /******************************************************************************
00445  *
00446  * Quiescence Calls
00447  *
00448  *****************************************************************************/
00456 
00458 extern void CkStartQD(int eIdx,const CkChareID *chare);
00460 extern void CkWaitQD(void);
00463 /******************************************************************************
00464  *
00465  * Miscellaneous Calls
00466  *
00467  *****************************************************************************/
00468 
00469 extern int CkMessageToEpIdx(void *msg);
00470 extern void CkPrintEntryMethod(int epIdx);
00471 extern void CkPrintChareName(int chareIdx);
00472 extern void CkSummary_MarkEvent(int);
00473 extern void CkSummary_StartPhase(int);
00474 extern int CkDisableTracing(int epIdx);
00475 extern void CkEnableTracing(int epIdx);
00476 
00477 #ifdef __cplusplus
00478 }
00479 #endif
00480 #endif
ck-core/charm.h
