Documentation #1777: Document message types in Charm++ message handler code 22/5022/4
authorNitin Bhat <nbhat4@illinois.edu>
Fri, 15 Mar 2019 14:49:22 +0000 (09:49 -0500)
committerEvan Ramos <evan@hpccharm.com>
Mon, 18 Mar 2019 21:52:35 +0000 (16:52 -0500)
Change-Id: Idf60bfd65f3bd74e1037aed72e6449284383a304

src/ck-core/charm.h
src/ck-core/ck.C
src/ck-core/init.C

index fb5494720868e1962168190d3baa9966afd00a3c..0c8881389f53fe776934a70d25f3296a9c0a334e 100644 (file)
@@ -316,32 +316,32 @@ extern void CkMigrateExt(int aid, int ndims, int *index, int toPe);
  *   Make sure the two remain synchronized if changing this one.
  ***/
 typedef enum {
-  NewChareMsg    =1,
-  NewVChareMsg   =2,
-  BocInitMsg     =3,
-  ForChareMsg    =4,
-  ForBocMsg      =5,
-  ForVidMsg      =6,
-  FillVidMsg     =7,
-  DeleteVidMsg   =8,
-  RODataMsg      =9,
-  ROMsgMsg       =10,
-  StartExitMsg   =11,
-  ExitMsg        =12,
-  ReqStatMsg     =13,
-  StatMsg        =14,
-  StatDoneMsg   =15,
-  NodeBocInitMsg =16,
-  ForNodeBocMsg  =17,
-  ArrayEltInitMsg =18,
-  ForArrayEltMsg  =19,
+  NewChareMsg     =1,               // Singleton chare creation message
+  NewVChareMsg    =2,               // Singleton virtual chare creation message
+  BocInitMsg      =3,               // Group creation message
+  ForChareMsg     =4,               // Singleton chare entry method message (non creation)
+  ForBocMsg       =5,               // Group entry method message (non creation)
+  ForVidMsg       =6,               // Singleton virtual chare entry method message (non creation)
+  FillVidMsg      =7,               // Message sent to fill a VidBlock on a virtual chare PE
+  DeleteVidMsg    =8,               // Message sent to delete a VidBlock on a virtual chare PE
+  RODataMsg       =9,               // Readonly Data Message (for user declared readonly variables)
+  ROMsgMsg        =10,              // Readonly message Message (for user declared readonly messages)
+  StartExitMsg    =11,              // Exit sequence trigger message
+  ExitMsg         =12,              // Exit sequence trigger message using user registered exit function
+  ReqStatMsg      =13,              // Request stats and warnings message
+  StatMsg         =14,              // Stats data message (Reduction)
+  StatDoneMsg     =15,              // Signal completion of stats reduction (Broadcast)
+  NodeBocInitMsg  =16,              // Nodegroup creation message
+  ForNodeBocMsg   =17,              // Nodegroup entry method message (non creation)
+  ArrayEltInitMsg =18,              // Array Element Initialization message
+  ForArrayEltMsg  =19,              // Array Element entry method message
   ForIDedObjMsg   =20,
 #if CMK_LOCKLESS_QUEUE
-  WarnMsg         =21,
-  WarnDoneMsg     =22,
-  LAST_CK_ENVELOPE_TYPE =23
+  WarnMsg         =21,              // Warning data message (Reduction)
+  WarnDoneMsg     =22,              // Signal completion of warnings reduction (Broadcast)
+  LAST_CK_ENVELOPE_TYPE =23         // Used for error-checking
 #else
-  LAST_CK_ENVELOPE_TYPE =21
+  LAST_CK_ENVELOPE_TYPE =21         // Used for error-checking
 #endif
 } CkEnvelopeType;
 
index e4e4a959c2a74e8565d80670ef27196cc0ab63ac..fb68f13a8eb8c61de387e3b1a1e941ba5113aed7 100644 (file)
@@ -1254,26 +1254,26 @@ void _processHandler(void *converseMsg,CkCoreState *ck)
 
   switch(env->getMsgtype()) {
 // Group support
-    case BocInitMsg :
+    case BocInitMsg : // Group creation message
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: BocInitMsg\n", CkMyPe());)
       // QD processing moved inside _processBocInitMsg because it is conditional
       //ck->process(); 
       if(env->isPacked()) CkUnpackMessage(&env);
       _processBocInitMsg(ck,env);
       break;
-    case NodeBocInitMsg :
+    case NodeBocInitMsg : // Nodegroup creation message
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: NodeBocInitMsg\n", CkMyPe());)
       if(env->isPacked()) CkUnpackMessage(&env);
       _processNodeBocInitMsg(ck,env);
       break;
-    case ForBocMsg :
+    case ForBocMsg : // Group entry method message (non creation)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: ForBocMsg\n", CkMyPe());)
       // QD processing moved inside _processForBocMsg because it is conditional
       if(env->isPacked()) CkUnpackMessage(&env);
       _processForBocMsg(ck,env);
       // stats record moved inside _processForBocMsg because it is conditional
       break;
-    case ForNodeBocMsg :
+    case ForNodeBocMsg : // Nodegroup entry method message (non creation)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: ForNodeBocMsg\n", CkMyPe());)
       // QD processing moved to _processForNodeBocMsg because it is conditional
       if(env->isPacked()) CkUnpackMessage(&env);
@@ -1282,37 +1282,39 @@ void _processHandler(void *converseMsg,CkCoreState *ck)
       break;
 
 // Array support
-    case ForArrayEltMsg:
+    case ForArrayEltMsg: // Array element entry method message
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: ForArrayEltMsg\n", CkMyPe());)
       if(env->isPacked()) CkUnpackMessage(&env);
       _processArrayEltMsg(ck,env);
       break;
 
 // Chare support
-    case NewChareMsg :
+    case NewChareMsg : // Singleton chare creation message
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: NewChareMsg\n", CkMyPe());)
       if(env->isPacked()) CkUnpackMessage(&env);
       _processNewChareMsg(ck,env);
       break;
-    case NewVChareMsg :
+    case NewVChareMsg : // Singleton virtual chare creation message
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: NewVChareMsg\n", CkMyPe());)
       if(env->isPacked()) CkUnpackMessage(&env);
       _processNewVChareMsg(ck,env);
       break;
-    case ForChareMsg :
+    case ForChareMsg : // Singeton chare entry method message (non creation)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: ForChareMsg\n", CkMyPe());)
       if(env->isPacked()) CkUnpackMessage(&env);
       _processForPlainChareMsg(ck,env);
       break;
-    case ForVidMsg   :
+    case ForVidMsg   : // Singleton virtual chare entry method message (non creation)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: ForVidMsg\n", CkMyPe());)
       _processForVidMsg(ck,env);
       break;
-    case FillVidMsg  :
+    case FillVidMsg  : // Message sent back from the real chare PE to the virtual chare PE to
+                       // fill the VidBlock (called when the real chare is constructed)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: FillVidMsg\n", CkMyPe());)
       _processFillVidMsg(ck,env);
       break;
-    case DeleteVidMsg  :
+    case DeleteVidMsg  : // Message sent back from the real chare PE to the virtual chare PE to
+                         // delete the Vidblock (called when the real chare is deleted by the destructor)
       TELLMSGTYPE(CkPrintf("proc[%d]: _processHandler with msg type: DeleteVidMsg\n", CkMyPe());)
       _processDeleteVidMsg(ck,env);
       break;
index 8a2ce4ddc488e363556eef08cafe7543130e8c5a..2565789a92c8d7c08b59f1feec6adcc88216544f 100644 (file)
@@ -596,7 +596,7 @@ static void _exitHandler(envelope *env)
 {
   DEBUGF(("exitHandler called on %d msgtype: %d\n", CkMyPe(), env->getMsgtype()));
   switch(env->getMsgtype()) {
-    case StartExitMsg:
+    case StartExitMsg: // Exit sequence trigger message
       CkAssert(CkMyPe()==0);
       if(_exitStarted) {
         CmiFree(env);
@@ -605,7 +605,7 @@ static void _exitHandler(envelope *env)
       _exitStarted = true;
 
       // else fall through
-    case ExitMsg:
+    case ExitMsg: // Exit sequence trigger message using user registered exit function
       CkAssert(CkMyPe()==0);
       if (!_CkExitFnVec.isEmpty()) {
         CmiFree(env);
@@ -637,7 +637,7 @@ static void _exitHandler(envelope *env)
       ConverseExit(_exitcode);
 #endif
       break;
-    case ReqStatMsg:
+    case ReqStatMsg: // Request stats and warnings message
 #if (defined(_FAULT_MLOG_) || defined(_FAULT_CAUSAL_))
       _messageLoggingExit();
 #endif
@@ -686,7 +686,7 @@ static void _exitHandler(envelope *env)
 #endif
       break;
 #if CMK_WITH_STATS
-    case StatMsg:
+    case StatMsg: // Stats data message (in response to ReqStatMsg)
     {
       CkAssert(CkMyPe()==0);
       statsHeader* header = (statsHeader*)EnvToUsr(env);
@@ -706,7 +706,7 @@ static void _exitHandler(envelope *env)
     }
     break;
 
-    case StatDoneMsg:
+    case StatDoneMsg: // Indicates completion of stats reduction
       DEBUGF(("[%d] Calling converse exit from StatDoneMsg \n",CkMyPe()));
       ConverseExit(_exitcode);
       if (CharmLibInterOperate)
@@ -714,7 +714,7 @@ static void _exitHandler(envelope *env)
       break;
 #endif
 #if CMK_WITH_WARNINGS
-    case WarnMsg:
+    case WarnMsg: // Warnings data message (in reponse to ReqStatMsg)
     {
       CkAssert(CkMyPe()==0);
       WarningMsg* msg = (WarningMsg*)EnvToUsr(env);
@@ -725,7 +725,7 @@ static void _exitHandler(envelope *env)
       CmiSyncBroadcastAllAndFree(env->getTotalsize(), (char*)env);
       break;
     }
-    case WarnDoneMsg:
+    case WarnDoneMsg: // Indicates completion of warnings reduction
       DEBUGF(("[%d] Calling converse exit from WarnDoneMsg \n",CkMyPe()));
       ConverseExit(_exitcode);
       if (CharmLibInterOperate)
@@ -953,7 +953,7 @@ static void _initHandler(void *msg, CkCoreState *ck)
   }
   
   switch (env->getMsgtype()) {
-    case BocInitMsg:
+    case BocInitMsg: // Group creation message
       if (env->getGroupEpoch()==0) {
         CkpvAccess(_numInitsRecd)++;
         // _qd->process() or ck->process() to update QD counters is called inside _processBocInitMsg
@@ -963,7 +963,7 @@ static void _initHandler(void *msg, CkCoreState *ck)
         (*CkpvAccess(_bocInitVec))[env->getGroupNum().idx] = env;
       } else _bufferHandler(msg);
       break;
-    case NodeBocInitMsg:
+    case NodeBocInitMsg: // Nodegroup creation message
       if (env->getGroupEpoch()==0) {
         CmiImmediateLock(CksvAccess(_nodeGroupTableImmLock));
         CksvAccess(_numInitNodeMsgs)++;
@@ -975,13 +975,13 @@ static void _initHandler(void *msg, CkCoreState *ck)
         // _qd->process() or ck->process() to update QD counters is called inside _processNodeBocInitMsg
       } else _bufferHandler(msg);
       break;
-    case ROMsgMsg:
+    case ROMsgMsg: // Readonly Message (for user declared readonly messages)
       CkpvAccess(_numInitsRecd)++;
       CpvAccess(_qd)->process();
       if(env->isPacked()) CkUnpackMessage(&env);
       _processROMsgMsg(env);
       break;
-    case RODataMsg:
+    case RODataMsg: // Readonly Data Message (for user declared readonly variables)
       CkpvAccess(_numInitsRecd)++;
       CpvAccess(_qd)->process();
       _numExpectInitMsgs = env->getCount();