doc: more section promotion in a coupla chapters
[charm.git] / doc / charm++ / inhertmplt.tex
1 \charmpp\ supports inheritance among \charmpp\ objects such as
2 chares, groups, and messages. This, along with facilities for generic
3 programming using \CC\ style templates for \charmpp\ objects, is a
4 major enhancement over the previous versions of \charmpp.
5
6 \section{Chare Inheritance}
7
8 \index{inheritance}
9
10 Chare inheritance makes it possible to remotely invoke methods of a base
11 chare \index{base chare} from a proxy of a derived
12 chare.\index{derived chare} Suppose a base chare is of type 
13 \uw{BaseChare}, then the derived chare of type \uw{DerivedChare} needs to be
14 declared in the \charmpp\ interface file to be explicitly derived from
15 \uw{BaseChare}. Thus, the constructs in the \texttt{.ci} file should look like:
16
17 \begin{alltt}
18   chare BaseChare \{
19     entry BaseChare(someMessage *);
20     entry void baseMethod(void);
21     ...
22   \}
23   chare DerivedChare : BaseChare \{
24     entry DerivedChare(otherMessage *);
25     entry void derivedMethod(void);
26     ...
27   \}
28 \end{alltt}
29
30 Note that the access specifier \kw{public} is omitted, because \charmpp\
31 interface translator only needs to know about the public inheritance,
32 and thus \kw{public} is implicit. A Chare can inherit privately from other
33 classes too, but the \charmpp\ interface translator does not need to know
34 about it, because it generates support classes ({\em proxies}) to remotely
35 invoke only \kw{public} methods.
36
37 The class definitions of both these chares should look like:
38
39 \begin{alltt}
40   class BaseChare : public Chare \{
41     // private or protected data
42     public:
43       BaseChare(someMessage *);
44       void baseMethod(void);
45   \};
46   class DerivedChare : public BaseChare \{
47     // private or protected data
48     public:
49       DerivedChare(otherMessage *);
50       void derivedMethod(void);
51   \};
52 \end{alltt}
53
54 Now, it is possible to create a derived chare, and invoke methods of base
55 chare from it, or to assign a derived chare proxy to a base chare proxy
56 as shown below:
57
58 \begin{alltt}
59   ...
60   otherMessage *msg = new otherMessage();
61   CProxy_DerivedChare *pd = new CProxy_DerivedChare(msg);
62   pd->baseMethod();     // OK
63   pd->derivedMethod();  // OK
64   ...
65   Cproxy_BaseChare *pb = pd;
66   pb->baseMethod();    // OK
67   pb->derivedMethod(); // COMPILE ERROR
68 \end{alltt}
69
70 Note that \CC\ calls the default constructor \index{default constructor} of the
71 base class from any constructor for the derived class where base class
72 constructor is not called explicitly. Therefore, one should always provide a
73 default constructor for the base class, or explicitly call another base
74 class constructor.
75
76 Multiple inheritance \index{multiple inheritance} is also allowed for Chares
77 and Groups. Often, one should make each of the base classes inherit
78 ``virtually'' from \kw{Chare} or \kw{Group}, so that a single copy of
79 \kw{Chare} or \kw{Group} exists for each multiply derived class.
80
81 Entry methods are inherited in the
82 same manner as methods of sequential \CC{} objects.  
83 To make an entry method virtual, just add the keyword \kw{virtual}
84 to the corresponding chare method-- no change is needed in the interface file.
85 Pure virtual entry methods also require no special description
86 in the interface file.
87
88
89 \section{Inheritance for Messages}
90
91 \index{message inheritance}
92
93 Messages cannot inherit from other messages.  A message can, however,
94 inherit from a regular \CC\ class.  For example:
95
96 \begin{alltt}
97 //In the .ci file:
98   message BaseMessage1;
99   message BaseMessage2;
100
101 //In the .h file:
102   class Base \{
103     // ...
104   \};
105   class BaseMessage1 : public Base, public CMessage_BaseMessage1 \{
106     // ...
107   \};
108   class BaseMessage2 : public Base, public CMessage_BaseMessage2 \{
109     // ...
110   \};
111 \end{alltt}
112
113 Messages cannot contain virtual methods
114 or virtual base classes unless you use a packed message.
115 Parameter marshalling has complete support for inheritance, virtual
116 methods, and virtual base classes via the PUP::able framework.
117
118
119 % ( I think the following is now a lie  OSL 7/5/2001 )  
120 %Similar to Chares, messages can also be derived from base messages. One needs
121 %to specify this in the \charmpp\ interface file similar to the Chare
122 %inheritance specification (that is, without the \kw{public} access specifier.)
123 %Message inheritance makes it possible to send a message of derived type to the
124 %method expecting a base class message.
125
126
127 \section{Generic Programming Using Templates}
128
129 \index{templates}
130
131 One can write ``templated'' code for Chares, Groups, Messages and other
132 \charmpp\  entities using familiar \CC\ template syntax (almost). The \charmpp\
133 interface translator now recognizes most of the \CC\ templates syntax,
134 including a variety of formal parameters, default parameters, etc. However, not
135 all \CC\ compilers currently recognize templates in ANSI drafts, therefore the
136 code generated by \charmpp\ for templates may not be acceptable to some current
137 \CC\ compilers
138
139 \newcommand{\longcompilerfootnote}{\footnote{ Most modern \CC\
140     compilers belong to one of the two camps. One that supports
141     Borland style template instantiation, and the other that supports
142     AT\&T Cfront style template instantiation. In the first, code is
143     generated for the source file where the instantiation is seen.
144     GNU \CC\ falls in this category.  In the second, which template is
145     to be instantiated, and where the templated code is seen is noted
146     in a separate area (typically a local directory), and then just
147     before linking all the template instantiations are
148     generated. Solaris CC 5.0 belongs to this category. For templates
149     to work for compilers in the first category such as for GNU \CC\
150     all the templated code needs to be visible to the compiler at the
151     point of instantiation, that is, while compiling the source file
152     containing the template instantiation. For a variety of reasons,
153     \charmpp\ interface translator cannot generate all the templated
154     code in the declarations file {\tt *.decl.h}, which is included in
155     the source file where templates are instantiated. Thus, for
156     \charmpp\ generated templates to work for GNU \CC\ even parts of
157     the definitions file {\tt *.def.h} should be included in the \CC\
158     source file. }}
159
160 Since many modern \CC\ compilers\longcompilerfootnote\ require that
161 the template definitions (in \emph{addition} to the template
162 declarations) be available in all sources which use them, you will
163 need to include the templated Charm definitions in your header file.
164 That is, given a module {\tt stlib}, in addition to having a line {\tt
165   \#include "stlib.decl.h"} in your header file (e.g. {\tt stlib.h}),
166 you also need the following lines towards the end of the file:
167
168 \begin{alltt}
169 #define CK_TEMPLATES_ONLY
170 #include "stlib.def.h"
171 #undef CK_TEMPLATES_ONLY
172 \end{alltt}
173
174 This has the effect of including into the header file only those
175 declarations which relate to templates.  You will \emph{still} need to
176 include the file {\tt stlib.def.h} \emph{again} in your implementation
177 sources (i.e., {\tt stlib.C}) in order to pick up the rest of the
178 (non-template-related) definitions.  Note that for completely
179 template-based libraries, this means that you might need to create an
180 implementation file {\tt stlib.C} when you otherwise wouldn't solely
181 for the purpose of making sure that the non-template definitions in
182 {\tt stlib.def.h} are included and compiled.
183
184 The \charmpp\ interface file should contain the template
185 definitions as well as the instantiation. For example, if a message
186 class \uw{TMessage} is templated with a formal type parameter 
187 \uw{DType}, then every instantiation of \uw{TMessage} should be specified
188 in the \charmpp\ interface file. An example will illustrate this better:
189 \index{template}
190
191 \begin{alltt}
192   template <class DType=int, int N=3> message TMessage;
193   message TMessage<>; // same as TMessage<int,3>
194   message TMessage<double>; // same as TMessage<double, 3>
195   message TMessage<UserType, 1>;
196 \end{alltt}
197
198 Note the use of default template parameters. It is not necessary for
199 template definitions and template instantiations to be part of the
200 same module.  Thus, templates could be defined in one module, and
201 could be instantiated in another module \index{module}, as long as the
202 module defining a template is imported into the other module using the
203 \kw{extern module} construct. Thus it is possible to build a standard
204 \charmpp\ template library. Here we give a flavor of possibilities:
205
206 \begin{alltt}
207 module SCTL \{
208   template <class dtype> message  Singleton;
209   template <class dtype> group Reducer \{
210     entry Reducer(void);
211     entry void submit(Singleton<dtype> *);
212   \}
213   template <class dtype> chare ReductionClient \{
214     entry void recvResult(Singleton<dtype> *);
215   \}
216 \};
217
218 module User \{
219   extern module SCTL;
220   message Singleton<int>;
221   group Reducer<int>;
222   chare RedcutionClient<int>;
223   chare UserClient : ReductionClient<int> \{
224     entry UserClient(void);
225   \}
226 \};
227 \end{alltt}
228
229 The \uw{Singleton} message is a template for storing one element of any
230 \uw{dtype}. The \uw{Reducer} is a group template for a spanning-tree reduction,
231 which is started by submitting data to the local branch. It also contains a
232 public method to register the \uw{ReductionClient} (or any of its derived
233 types), which acts as a callback to receive results of a reduction.