doc/charm++/modules.tex

   1 \subsection{Modules}
   2
   3 \subsubsection{Structure of a \charmpp\ Program}
   4
   5 A \charmpp\ program is structurally similar to a \CC{} program.  Most of a
   6 \charmpp\ program {\em is} \CC{} code.\footnote{\bf Constraint: The \CC{} code
   7 cannot, however, contain global or static variables.} The main syntactic units
   8 in a \charmpp\ program are class definitions. A \charmpp\ program can be
   9 distributed across several source code files.
  10
  11 There are five disjoint categories of objects (classes) in \charmpp:
  12
  13 \begin{itemize}
  14 \item Sequential objects: as in \CC{}
  15 \item Chares (concurrent objects) \index{chare}
  16 \item Chare Groups \index{chare groups} (a form of replicated objects)
  17 \index{group}
  18 \item Chare Arrays \index{chare arrays} (an indexed collection of chares)
  19 \index{array}
  20 \item Messages (communication objects)\index{message}
  21 \end{itemize}
  22
  23 The user's code is written in \CC{} and interfaces with the \charmpp\ system as
  24 if it were a library containing base classes, functions, etc.  A translator is
  25 used to generate the special code needed to handle \charmpp\ constructs.  This
  26 translator generates \CC{} code that needs to be compiled with the user's code.
  27
  28 Interfaces to the \charmpp\ objects (such as messages, chares, readonly
  29 variables etc.) \index{message}\index{chare}\index{readonly} have to be
  30 declared in \charmpp\ interface files. Typically, such entities are grouped
  31 \index{module} into {\em modules}. A \charmpp\ program may consists of multiple
  32 modules.  One of these modules is declared to be a \kw{mainmodule}. All the
  33 modules that are ``reachable'' from the \kw{mainmodule} via the \kw{extern}
  34 construct are included in a \charmpp\ program.
  35
  36 The \charmpp\ interface file has the suffix ``.ci''.  The \charmpp\ interface
  37 translator parses this file and produces two files (with suffixes ``.decl.h''
  38 and ``.def.h'', {\em for each module declared in the ``.ci'' file}), that
  39 contain declarations (interface) and definitions (implementation)of various
  40 translator-generated entities. If the name of a module is \uw{MOD}, then the
  41 files produced by the \charmpp\ interface translator are named \uw{MOD.decl.h}
  42 and \uw{MOD.def.h}.\footnote{Note that the interface file for module \uw{MOD}
  43 need not be named \uw{MOD.ci}. Indeed one ``.ci'' file may contain interface
  44 declarations for multiple modules, and the translator will produce one pair of
  45 declaration and definition files for each module.}  We recommend that the
  46 declarations header file be included at the top of the header file (\uw{MOD.h})
  47 for module \uw{MOD}, and the definitions file be included at the bottom of the
  48 code for module (\uw{MOD.C}).\footnote{In the earlier version of interface
  49 translator, these files used to be suffixed with ``.top.h'' and ``.bot.h'' for
  50 this reason.}
  51
  52 A simple \charmpp\ program is given below:
  53
  54 \begin{alltt}
  55 ///////////////////////////////////////
  56 // File: pgm.ci
  57
  58 mainmodule Hello \{
  59   readonly CProxy_HelloMain mainProxy;
  60   mainchare HelloMain \{
  61     entry HelloMain(); // implicit CkArgMsg * as argument
  62     entry void PrintDone(void);
  63   \};
  64   group HelloGroup \{
  65     entry HelloGroup(void);
  66   \};
  67 \};
  68
  69 ////////////////////////////////////////
  70 // File: pgm.h
  71 #include "Hello.decl.h" // Note: not pgm.decl.h
  72
  73 class HelloMain: public Chare \{
  74   public:
  75     HelloMain(CkArgMsg *);
  76     void PrintDone(void);
  77   private:
  78     int count;
  79 \};
  80
  81 class HelloGroup: public Group \{
  82   public:
  83     HelloGroup(void);
  84 \};
  85
  86 /////////////////////////////////////////
  87 // File: pgm.C
  88 #include "pgm.h"
  89
  90 CProxy_HelloMain mainProxy;
  91
  92 HelloMain::HelloMain(CkArgMsg *msg) \{
  93   delete msg;
  94   count = 0;
  95   mainProxy=thishandle;
  96   CProxy_HelloGroup::ckNew(); // Create a new "HelloGroup"
  97 \}
  98
  99 void HelloMain::PrintDone(void) \{
 100   count++;
 101   if (count == CkNumPes()) \{ // Wait for all group members to finish the printf
 102     CkExit();
 103   \}
 104 \}
 105
 106 HelloGroup::HelloGroup(void) \{
 107   ckout << "Hello World from processor " << CkMyPe() << endl;
 108   mainProxy.PrintDone();
 109 \}
 110
 111 #include "Hello.def.h" // Include the Charm++ object implementations
 112
 113 /////////////////////////////////////////
 114 // File: Makefile
 115
 116 pgm: pgm.ci pgm.h pgm.C
 117       charmc -c pgm.ci
 118       charmc -c pgm.C
 119       charmc -o pgm pgm.o -language charm++
 120
 121 \end{alltt}
 122
 123 \uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm Kernel starts
 124 execution of this program by creating an instance of \uw{HelloMain} on
 125 processor 0. The HelloMain constructor creates a chare group
 126 \uw{HelloGroup}, and stores a handle to itself and returns. The call to
 127 create the group returns immediately after directing Charm Kernel to perform
 128 the actual creation and invocation.  Shortly after, the Charm Kernel will
 129 create an object of type \uw{HelloGroup} on each processor, and call its
 130 constructor. The constructor will then print ``Hello World...'' and then
 131 call the \uw{PrintDone} method of \uw{HelloMain}. The \uw{PrintDone} method
 132 calls \kw{CkExit} after all group members have called it (i.e., they have
 133 finished printing ``Hello World...''), and the \charmpp program exits.
 134
 135 \subsubsection{Functions in the ``decl.h'' and ``def.h'' files}
 136
 137 The \texttt{decl.h} file provides declarations for the proxy classes of the
 138 concurrent objects declared in the ``.ci'' file (from which the \texttt{decl.h}
 139 file is generated). So the \uw{Hello.decl.h} file will have the declaration of
 140 the class CProxy\_HelloMain. Similarly it will also have the declaration for
 141 the HelloGroup class.
 142
 143 This class will have functions to create new instances of the chares and
 144 groups, like the function \kw{ckNew}. For \uw{HelloGroup} this function creates
 145 an instance of the class \uw{HelloGroup} on all the processors.
 146
 147 The proxy class also has functions corresponding to the entry methods defined
 148 in the ``.ci'' file. In the above program the method wait is declared in
 149 \uw{CProxy\_HelloMain} (proxy class for \uw{HelloMain}).
 150
 151 The proxy class also provides static registration functions used by the
 152 \charmpp{} runtime.  The \texttt{def.h} file has a registration function
 153 (\uw{\_\_registerHello} in the above program) which calls all the registration
 154 functions corresponding to the readonly variables and entry methods declared in
 155 the module.
 156