msgQ: Use the datatype for msg prios as specified by user (CMK_MSG_PRIO_TYPE)
[charm.git] / doc / charisma / seqcode.tex
1 \subsubsection{Sequential Files}
2 The programmer supplies the sequential code for each class as necessary. The
3 files should be named in the form of class name with appropriate file extension.
4 The header file is not really an ANSI C header file. Instead, it is the
5 sequential portion of the class's declaration. Charisma will generate the class 
6 declaration from the orchestration code, and incorporate the sequential portion
7 in the final header file. For example, if a molecular dynamics simulation has
8 the following classes (as declared in the orchestration code):
9
10 \begin{SaveVerbatim}{foodecl}
11     class MDMain : MainChare;
12     class Cell : ChareArray3D;
13     class CellPair : ChareArray6D;
14 \end{SaveVerbatim}
15 \smallfbox{\BUseVerbatim{foodecl}}
16
17 The user is supposed to prepare the following sequential files for the classes:
18 MDMain.h, MDMain.C, Cell.h, Cell.C, CellPair.h and CellPair.C, unless a class
19 does not need sequential declaration and/or definition code. Please refer to the
20 example in the Appendix. 
21
22 For each class, a member function ``void initialize(void)'' can be defined and
23 the generated constructor will automatically call it. This saves the trouble of 
24 explicitly call initialization code for each array object. 
25
26 \subsubsection{Producing and Consuming Functions}
27 The C/C++ source code is nothing different than ordinary sequential source code,
28 except for the producing/consuming part. For consumed parameters, a function
29 treat them just like normal parameters passed in. To handle produced parameters, 
30 the sequential code needs to do two special things. First, the function should 
31 have extra parameter for output parameters. The parameter type is keyword \code{outport},
32 and the parameter name is the same as appeared in the orchestration code. Second,
33 in the body of the function, the keyword \code{produce} is used to connect the 
34 orchestration parameter and the local variables whose value will be sent out, in 
35 a format of a function call, as follows.
36
37 \begin{SaveVerbatim}{foodecl}
38     produce(produced_parameter, local_variable[, size_of_array]);
39 \end{SaveVerbatim}
40 \smallfbox{\BUseVerbatim{foodecl}}
41
42 When the parameter represents a data array, we need the additional
43 \code{size\_of\_array} to specify the size of the data array. 
44
45 The dimensionality of an orchestration parameter is divided into two parts: 
46 its dimension in the orchestration code, which is implied by the dimensionality
47 of the object arrays the parameter is associated, and the local dimensionality,
48 which is declared in the declaration section. The orchestration dimension is not
49 explicitly declared anywhere, but it is derived from the object arrays. For 
50 instance, in the 1D Jacobi worker example, ``lb'' and ``rb'' has the same 
51 orchestration dimensionality of workers, namely 1D of size [16]. The local
52 dimensionality is used when the parameter is associated with local variables 
53 in sequential code. Since ``lb'' and ``rb'' are declared to have the local
54 type and dimension of ``double [512]'', the producing statement should connect
55 it with a local variable of ``double [512]''.
56
57 \begin{SaveVerbatim}{foodecl}
58     void JacobiWorker::produceBorders(outport lb, outport rb){
59       . . .
60       produce(lb,localLB,512);
61       produce(rb,localRB,512);
62     }
63 \end{SaveVerbatim}
64 \smallfbox{\BUseVerbatim{foodecl}}
65
66 Special cases of the produced/consumed parameters involve scatter/gather
67 operations. In scatter operation, since an additional dimension is implied in
68 the produced parameter, we the \code{local\_variable} should have additional
69 dimension equal to the dimension over which the scatter is performed. Similarly,
70 the input parameter in gather operation will have an additional dimension the
71 same size of the dimension of the gather operation.
72
73 For reduction, one additional parameter of type char[] is added to specify the
74 reduction operation. Built-in reduction operations are ``+'' (sum), ``*'' (product),
75 ``$<$'' (minimum), ``$>$'' (maximum) for basic data types. For instance the 
76 following statements takes the sum of all local value of \code{result} and 
77 for output in \code{sum}.
78
79 \begin{SaveVerbatim}{foodecl}
80     reduce(sum, result, ``+'');
81 \end{SaveVerbatim}
82 \smallfbox{\BUseVerbatim{foodecl}}
83
84 If the data type is a user-defined class, then you might use the function or
85 operator defined to do the reduction. For example, assume we have a class
86 called ``Force'', and we have an ``add'' function (or a ``+'' operator) defined.
87
88 \begin{SaveVerbatim}{foodecl}
89     Force& Force::add(const Force& f);
90 \end{SaveVerbatim}
91 \smallfbox{\BUseVerbatim{foodecl}}
92
93 In the reduction to sum all the local forces, we can use
94
95 \begin{SaveVerbatim}{foodecl}
96     reduce(sumForces, localForce, "add");
97 \end{SaveVerbatim}
98 \smallfbox{\BUseVerbatim{foodecl}}
99
100 \subsubsection{Miscellaneous Issues}
101 In sequential code, the user can access the object's index by a keyword 
102 ``thisIndex''. The index of 1-D to 6-D object arrays are:
103
104 \begin{SaveVerbatim}{foodecl}
105   1D: thisIndex
106   2D: thisIndex.{x,y}
107   3D: thisIndex.{x,y,z}
108   4D: thisIndex.{w,x,y,z}
109   5D: thisIndex.{v,w,x,y,z}
110   6D: thisIndex.{x1,y1,z1,x2,y2,z2}
111 \end{SaveVerbatim}
112 \smallfbox{\BUseVerbatim{foodecl}}
113