844e6228a095f238838664a2ab00b0ccaadd7b3e
[charm.git] / doc / charm++ / modules.tex
1 A \charm program is essentially a \CC program where some components describe
2 its parallel structure. Sequential code can be written using any programming
3 technologies that cooperate with the \CC toolchain. This includes C and
4 Fortran. Parallel entities in the user's code are written in \CC{}. These
5 entities interact with the \charm framework via inherited classes and function
6 calls.
7
8
9 \section{.ci Files}
10 \index{ci}
11 All user program components that comprise its parallel interface (such as
12 messages, chares, entry methods, etc.) are granted this elevated status by
13 declaring or describing them in separate \emph{charm interface} description
14 files. These files have a \emph{.ci} suffix and adopt a \CC-like declaration
15 syntax with several additional keywords. In some declaration contexts, they
16 may also contain some sequential \CC source code.
17 %that is embedded unmodified into the generated code.
18 \charm parses these interface descriptions and generates \CC code (base
19 classes, utility classes, wrapper functions etc.) that facilitates the
20 interaction of the user program's entities with the framework.  A program may
21 have several interface description files.
22
23
24 \section{Modules}
25 \index{module}
26 The top-level construct in a \ci file is a named container for interface
27 declarations called a \kw{module}. Modules allow related declarations to be
28 grouped together, and cause generated code for these declarations to be grouped
29 into files named after the module. Modules cannot be nested, but each \ci file
30 can have several modules. Modules are specified using the keyword \kw{module}.
31
32 \begin{alltt}
33 module myFirstModule \{
34     // Parallel interface declarations go here
35     ...
36 \};
37 \end{alltt}
38
39
40 \section{Generated Files}
41 \index{decl}\index{def}
42
43 Each module present in a \ci file is parsed to generate two files. The basename
44 of these files is the same as the name of the module and their suffixes are
45 \emph{.decl.h} and \emph{.def.h}. For e.g., the module defined earlier will
46 produce the files ``myFirstModule.decl.h'' and ``myFirstModule.def.h''. As the
47 suffixes indicate, they contain the declarations and definitions respectively,
48 of all the classes and functions that are generated based on the parallel
49 interface description.
50
51 We recommend that the header file containing the declarations (decl.h) be
52 included at the top of the files that contain the declarations or definitions
53 of the user program entities mentioned in the corresponding module. The def.h
54 is not actually a header file because it contains definitions for the generated
55 entities. To avoid multiple definition errors, it should be compiled into just
56 one object file. A convention we find useful is to place the def.h file at the
57 bottom of the source file (.C, .cpp, .cc etc.) which includes the definitions
58 of the corresponding user program entities.
59
60 \experimental
61 It should be noted that the generated files have no dependence on the name of the \ci
62 file, but only on the names of the modules. This can make automated dependency-based
63 build systems slightly more complicated. We adopt some conventions to ease this process.
64 This is described in~\ref{AppendixSectionDescribingPhilRamsWorkOnCi.stampAndCharmc-M}.
65
66
67 \section{Module Dependencies}
68 \index{extern}
69
70 A module may depend on the parallel entities declared in another module. It can
71 express this dependency using the \kw{extern} keyword. \kw{extern}ed modules
72 do not have to be present in the same \ci file.
73
74 \begin{alltt}
75 module mySecondModule \{
76
77     // Entities in this module depend on those declared in another module
78     extern module myFirstModule;
79
80     // More parallel interface declarations
81     ...
82 \};
83 \end{alltt}
84
85 The \kw{extern} keyword places an include statement for the decl.h file of the
86 \kw{extern}ed module in the generated code of the current module. Hence,
87 decl.h files generated from \kw{extern}ed modules are required during the
88 compilation of the source code for the current module. This is usually required
89 anyway because of the dependencies between user program entities across the two
90 modules.
91
92 \section{The Main Module and Reachable Modules}
93 \index{mainmodule}
94
95 \charm software can contain several module definitions from several
96 independently developed libraries / components. However, the user program must
97 specify exactly one module as containing the starting point of the program's
98 execution. This module is called the \kw{mainmodule}. Every \charm program
99 has to contain precisely one \kw{mainmodule}.
100
101 All modules that are ``reachable'' from the \kw{mainmodule} via a chain of
102 \kw{extern}ed module dependencies are included in a \charm program. More
103 precisely, during program execution, the \charm runtime system will recognize
104 only the user program entities that are declared in reachable modules. The
105 decl.h and def.h files may be generated for other modules, but the runtime
106 system is not aware of entities declared in such unreachable modules.
107
108 \begin{alltt}
109 module A \{
110     ...
111 \};
112
113 module B \{
114     extern module A;
115     ...
116 \};
117
118 module C \{
119     extern module A;
120     ...
121 \};
122
123 module D \{
124     extern module B;
125     ...
126 \};
127
128 module E \{
129     ...
130 \};
131
132 mainmodule M \{
133     extern module C;
134     extern module D;
135     // Only modules A, B, C and D are reachable and known to the runtime system
136     // Module E is unreachable via any chain of externed modules
137     ...
138 \};
139 \end{alltt}
140
141
142 \section{Including other headers}
143 \index{include}
144
145 There can be occasions where code generated from the module definitions
146 requires other declarations / definitions in the user program's sequential
147 code. Usually, this can be achieved by placing such user code before the point
148 of inclusion of the decl.h file. However, this can become laborious if the
149 decl.h file has to included in several places. \charm supports the keyword
150 \kw{include} in \ci files to permit the inclusion of any header directly into
151 the generated decl.h files.
152
153 \begin{alltt}
154 module A \{
155     include "myUtilityClass.h"; //< Note the semicolon
156     // Interface declarations that depend on myUtilityClass
157     ...
158 \};
159
160 module B \{
161     include "someUserTypedefs.h";
162     // Interface declarations that require user typedefs
163     ...
164 \};
165
166 module C \{
167     extern module A;
168     extern module B;
169     // The user includes will be indirectly visible here too
170     ...
171 \};
172 \end{alltt}
173
174
175 \section{The main() function}
176
177 The \charmpp framework implements its own main\(\) function and retains control
178 until the parallel execution environment is initialized and ready for executing
179 user code. Hence, the user program must not define a \emph{main()} function.
180 Control enters the user code via the \kw{mainchare} of the \kw{mainmodule}.
181 This will be discussed in further detail in~\ref{mainchare}.
182
183 Using the facilities described thus far, the parallel interface declarations
184 for a \charm program can be spread across multiple ci files and multiple
185 modules, permitting good control over the grouping and export of parallel API.
186 This aids the encapsulation of parallel software.
187
188 \section{\kw{initnode} and \kw{initproc} Routines}
189 \input{othercalls}
190
191 \section{Compiling \charm Programs}
192 \index{charmc}
193
194 \charm provides a compiler-wrapper called \kw{charmc} that handles all \ci, C,
195 \CC and fortran source files that are part of a user program. Users can invoke
196 charmc to parse their interface descriptions, compile source code and link
197 objects into binaries. It also links against the appropriate set of charm
198 framework objects and libraries while producing a binary. \kw{charmc} and its functionality
199 is described in~\ref{sec:compile}.
200