Improving documentation for scheduling routines.
authorIsaac Dooley <idooley2@illinois.edu>
Fri, 18 Sep 2009 22:33:29 +0000 (22:33 +0000)
committerIsaac Dooley <idooley2@illinois.edu>
Fri, 18 Sep 2009 22:33:29 +0000 (22:33 +0000)
doc/doxygen/src/main_page.C
src/conv-core/convcore.c
src/conv-core/converse.h
src/conv-core/queueing.c
src/conv-core/queueing.h
src/util/conv-lists.C
src/util/conv-lists.h

index 7d8defd9e07f6559d702e0a61c4f52d6d537be78..1b4872a90968de6ebad9a77cfa270760168d4723 100644 (file)
 
 <tr><td>
 Charm++:
-<p><ul>
-<li> <a href="group__CkArray.shtml">Arrays</a>,
-<li> Load balancer,
-<li> <a href="group__Comlib.shtml">Comlib</a>,
-<li> <a href="group__CkPerf.shtml">Tracing</a>,
-<li>Reductions,
-<li> <a href="group__CkArrayImpl.shtml">Array Implementation</a>
-<li> <a href="group__Ck.shtml">Groups and Chares</a>,  
-<li> <a href="group__CkRegister.shtml">Registration</a>, 
-<li> <a href="group__CkQD.shtml">Quiescence detection</a>, 
-<li> <a href="group__CkFutures.shtml">Futures</a>,
-<li> <a href="group__CkInit.shtml">Startup</a>,
-<li> <a href="group__CkEnvelope.shtml">Message Envelope</a>,
-<li> <a href="group__CharmScheduler.shtml">Charm++ Scheduler</a>, 
-<li> Translator
-<li> SDAG
-</ul>
+ -  \ref CkArray "Arrays"
+ -  Load balancer
+ -  \ref Comlib "Comlib"
+ -  \ref CkPerf "Tracing"
+ -  Reductions
+ -  \ref CkArrayImpl "Array Implementation"
+ -  \ref Ck "Groups and Chares"
+ -  \ref CkRegister "Registration"
+ -  \ref CkQD "Quiescence detection" 
+ -  \ref CkFutures "Futures"
+ -  \ref CkInit "Startup"
+ -  Message Envelopes
+ -  \ref CharmScheduler "Charm++ Scheduler"
+ -  Translator
+ -  SDAG
+
 </td></tr>
  
  <tr><td>
  Converse:
-<p><ul>
-<li> <a href="group__Converse.shtml">core</a>,
-<li> <a href="group__Scheduler.shtml">Converse Scheduler</a>, 
-<li> threads, 
-<li> memory allocation,
-<li> conditions, 
-<li> random numbers, 
-<li> converse client/server (CCS).
-<li> Converse tracing, 
-<li> parameter marshalling (CPM),
-<li> quiescence.
+ -  \ref Converse "Converse Core"
+ -  \ref ConverseScheduler "Converse Scheduler"
+ -  threads
+ -  memory allocation
+ -  conditions
+ -  random numbers
+ -  converse client/server (CCS)
+ -  Converse tracing
+ -  parameter marshalling (CPM)
+ - quiescence
 </ul>
  </td></tr>
  
  
  
  <tr><td>
- <a href="group__Machine.shtml">Converse Machine Layers</a>:
- <p><ul>
- <li><a href="group__NET.shtml">net</a>
- <li> ...
- </ul>
+ \ref Machine "Converse Machine Layers":
+ -  \ref NET "net"
+ -  ...
  </td></tr>
  
  
  <tr><td>
  Converse Configuration Layer:
-<p><ul>
-<li>build system
-<li>charmc
-<li>configure script
-<li>conv-mach.h/.sh
-</ul>
+ - build system
+ - charmc
+ - configure script
+ - conv-mach.h/.sh
  </td></tr>
  
  
 <tr><td>
 <p>Libraries:
 <p>Communication: Barrier, commlib, multicast, sparseReducer, sparseContiguousReducer
 <P>Languages: ARMCI, AMPI, TCharm, taskGraph, search
-<p>Frameworks: <a href="group__ParFUM.shtml">ParFUM</a>, IFEM, IDXL, Collide, MBlock, AMR
+<p>Frameworks: \ref ParFUM "ParFUM", IFEM, IDXL, Collide, MBlock, AMR
 <p>Visualization: liveViz, liveViz3d, netFEM
 </td></tr>
  
index c031d05b997986128d007e173a4e63abecb48248..e9876ea24cc9180bed7dbaa4d8f7c8da99c6ad5d 100644 (file)
   the correspondent method in a remote processor. This is done through the
   converse header (which has few common fields, but is architecture dependent).
 
-  @defgroup Scheduler 
+  @defgroup ConverseScheduler 
   \brief The portion of Converse responsible for scheduling the execution of 
   incoming messages.
+  
+  Converse provides a scheduler for message delivery: methods can be registered to 
+  the scheduler, and then messages allocated through CmiAlloc can be sent to 
+  the correspondent method in a remote processor. This is done through the
+  converse header (which has few common fields, but is architecture dependent).
+
+  In converse the CsdScheduleForever() routine will run an infinite while loop that 
+  looks for available messages to processes from the message queue. Messages in the 
+  queue are dequeued by the CsdNextMessage() routine. When a 
+  message is taken from the queue it is then passed into CmiHandleMessage() which
+  calls the handler associated with the message.
+
+  Incoming messages that are destined for Charm++ will be passed to the 
+  \ref CharmScheduler "charm scheduling routines".
 
   @file
   converse main core
   @ingroup Converse
-  @ingroup Scheduler
+  @ingroup ConverseScheduler
  
   @addtogroup Converse
   @{
@@ -1271,7 +1285,7 @@ void (*handler)();
 #endif
 
 /** 
- *  @addtogroup Scheduler
+ *  @addtogroup ConverseScheduler
  *  @{
  */
 
@@ -1348,6 +1362,7 @@ void CsdEndIdle(void)
 
 extern int _exitHandlerIdx;
 
+/** Takes a message and calls its corresponding handler. */
 void CmiHandleMessage(void *msg)
 {
 /* this is wrong because it counts the Charm++ messages in sched queue
@@ -1503,6 +1518,7 @@ extern void CkClearAllArrayElements();
 
 extern void machine_OffloadAPIProgress();
 
+/** The main scheduler loop that repeatedly executes messages from a queue, forever. */
 void CsdScheduleForever(void)
 {
   #if CMK_CELL
index be3c59f8783ed372a8b7411e71b47ad99d946709..95375d9cac348fa41e6304023917f3b76f2df156 100644 (file)
@@ -31,7 +31,8 @@
   - Csv, Converse node-shared variable.  Global variables 
      shared by all processors of a node (beware of thread safety!)
 
-  @addtogroup CharmScheduler
+  @ingroup CharmScheduler
+  @ingroup ConverseScheduler
 
 */
 #ifndef CONVERSE_H
@@ -799,8 +800,10 @@ extern void __cmi_assert(const char *, const char *, int);
 
 typedef void (*CmiStartFn)(int argc, char **argv);
 
-/********* CSD - THE SCHEDULER ********/
-
+/********* CSD - THE SCHEDULER ********
+  @addtogroup ConverseScheduler
+  @{
+*/
 CpvExtern(int, _ccd_numchecks);
 extern void  CcdCallBacks();
 #define CsdPeriodic() do{ if (CpvAccess(_ccd_numchecks)-- <= 0) CcdCallBacks(); } while(0)
@@ -836,6 +839,7 @@ extern  int CsdScheduleCount(int maxmsgs);
 extern void CsdSchedulePoll(void);
 
 #define CsdExitScheduler()  (CpvAccess(CsdStopFlag)++)
+/** @} */
 
 #if CMK_SPANTREE_USE_COMMON_CODE
 
index ce062a5604bf8380db89caf9ee60b8c7610b3a61..cedb4b82e7491bdc76f61e9af48c5dccf0eb3e45 100644 (file)
     negative priorities. The positive and negative priorty queues are actually heaps.
 
 
-    The charm++ messages are only scheduled after the converse message queues
-    have been emptied. After that, a message is pulled from the Charm++ queue
-    through a call to CqsDequeue().
+    The charm++ messages are only scheduled after the \ref ConverseScheduler "converse message queues"
+    have been emptied:
 
+    - CsdScheduleForever() is the commonly used Converse scheduler loop
+       - CsdNextMessage()
+          - First processes converse message from a  \ref ConverseScheduler "converse queue" if one exists using CdsFifo_Dequeue() 
+          - Then if no converse message was found, call CqsDequeue() which gets a charm++ message to execute if one exists
 
+
+    @file
+    Implementation of queuing data structure functions.
+    @ingroup CharmScheduler
+    
     @addtogroup CharmScheduler
     @{
 */
index 30a6b72a11c59cc0dea58cbd11823a65a74a2933..6a058476ed0cf8dfe50dbc08aae539780fd2d44c 100644 (file)
 
 
 /** 
-   @addtogroup CharmScheduler
-   @{
+    @file 
+    Declarations of queuing data structure functions.
+    @ingroup CharmScheduler   
+
+    @addtogroup CharmScheduler
+    @{
  */
 
 
index 245f9effbb92527920b7f2bb29914fdd6e2b333a..173cdedda90ff4a1d306b6f360149091a9f22a1e 100644 (file)
@@ -2,7 +2,11 @@
 #include "cklists.h"
 
 /** 
- *  @addtogroup Scheduler
+ * @file 
+ * Declarations of CdsFifo* routines
+ *
+ *  @ingroup ConverseScheduler
+ *  @addtogroup ConverseScheduler
  *  @{
  */
 
index 09452d6ea13f057f9e4a88f309982ec6a8953b1f..8f2cb55eaa32432a4d6cbd75e6317a9ff32a2092 100644 (file)
@@ -5,11 +5,13 @@
 extern "C" {
 #endif
 
-
-
 /** 
- *  @addtogroup Scheduler
- *  @{
+  @file 
+  Definitions of CdsFifo routines.
+  @ingroup ConverseScheduler
+
+  @addtogroup ConverseScheduler
+  @{
  */
 typedef void *CdsFifo;
 
@@ -25,12 +27,7 @@ int     CdsFifo_Empty(CdsFifo q);
 void *  CdsFifo_Peek(CdsFifo q);
 int     CdsFifo_Length(CdsFifo q);
 
-
-/** 
- *   @}
- */
-
-
+/** @} */
 
 #ifdef __cplusplus
 }