09a6b0921a526b75093664afc17d1bc32779f1b7
[charm.git] / 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 consist 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