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{Compiling \charm Programs}
 189 \index{charmc}
 190
 191 \charm provides a compiler-wrapper called \kw{charmc} that handles all \ci, C,
 192 \CC and fortran source files that are part of a user program. Users can invoke
 193 charmc to parse their interface descriptions, compile source code and link
 194 objects into binaries. It also links against the appropriate set of charm
 195 framework objects and libraries while producing a binary. \kw{charmc} and its functionality
 196 is described in~\ref{sec:compile}.
 197