Still improving manual.
[charm.git] / doc / converse / cpvmacros.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 % RCS INFORMATION:
3 %
4 %       $RCSfile$
5 %       $Author$        $Locker$                $State$
6 %       $Revision$      $Date$
7 %
8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 % DESCRIPTION:
10 %
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 % REVISION HISTORY:
13 %
14 % $Log$
15 % Revision 1.7  1997-06-26 05:16:22  jyelon
16 % Still improving manual.
17 %
18 % Revision 1.6  1997/06/25 06:53:48  jyelon
19 % Just trying to make this whole manual make more sense.
20 %
21 % Revision 1.5  1995/11/16 22:11:11  milind
22 % removed hardwired reference.
23 %
24 % Revision 1.4  1995/11/01  21:16:23  milind
25 % Added index entries.
26 %
27 % Revision 1.3  1995/10/30  17:33:54  milind
28 % Changed Cth variables macros to Ctv macros.
29 % Added "More on Shared Memory Machines" section.
30 %
31 % Revision 1.2  1995/10/27  21:02:54  milind
32 % Integrated into Manual.
33 %
34 % Revision 1.1  1995/10/26  21:08:23  gursoy
35 % Initial revision
36 %
37 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38
39 \chapter{Machine Model and Global Variables}
40
41 Converse treats the parallel machine as a collection of nodes, where
42 each node comprises of a number of processors that share memory.  In
43 some cases, the number of processors per node may be exactly one.  In
44 addition, each of the processors may have multiple threads running on
45 them which share code and data but have different stacks.
46
47 Different vendors are not consistent about how they treat global and static
48 variables.  Most vendors write C compilers in which global variables are
49 shared among all the processors in the node.  A few vendors write C
50 compilers where each processor has its own copy of the global variables.
51 In theory, it would also be possible to design the compiler so that
52 each thread has its own copy of the global variables.
53
54 The lack of consistency across vendors, makes it very hard to write a
55 portable program.  The fact that most vendors make the globals shared
56 is inconvenient as well, usually, you don't want your globals to be
57 shared.  For these reasons, we added ``pseudoglobals'' to Converse.
58 These act much like C global and static variables, except that you have
59 explicit control over the degree of sharing.
60
61 \section{Converse PseudoGlobals}
62
63 Three classes of pseudoglobal variables are supported: node-private,
64 process-private, and thread-private variables.
65
66 \begin{description}
67 \item[Node-private global variables] are specific to a node. They are
68      shared among all the processes within the node.
69 \item[Process-private global variables]  are specific to a process. They are
70      shared among all the threads within the process.
71 \item[Thread-private global variables] are specific to a thread. They are 
72      truely private.
73 \end{description}
74
75 There are five macros for each class. These macros are for
76 declaration, static declaration, extern declaration, initialization,
77 and access. The declaration, static and extern specifications have the
78 same meaning as in C. In order to support portability, however, the
79 global variables must be installed properly, by using the
80 initialization macros.  For example, if the underlying machine is a
81 simulator for the machine model supported by Converse, then the
82 thread-private variables must be turned into arrays of variables.
83 Initialize and Access macros hide these details from the user.  It is
84 possible to use global variables without these macros, as supported by
85 the underlying machine, but at the expense of portability.
86
87 Macros for node-private variables:
88 \begin{verbatim}
89 CsvDeclare(type,variable)
90 CsvStaticDeclare(type,variable)
91 CsvExtern(type,variable)
92 CsvInitialize(type,variable)
93 CsvAccess(variable)
94 \end{verbatim}
95
96 \index{CsvDeclare}
97 \index{CsvStaticDeclare}
98 \index{CsvExtern}
99 \index{CsvInitialize}
100 \index{CsvAccess}
101
102 Macros for process-private variables:
103 \begin{verbatim}
104 CpvDeclare(type,variable)
105 CpvStaticDeclare(type,variable)
106 CpvExtern(type,variable)
107 CpvInitialize(type,variable)
108 CpvAccess(variable)
109 \end{verbatim}
110 \index{CpvDeclare}
111 \index{CpvStaticDeclare}
112 \index{CpvExtern}
113 \index{CpvInitialize}
114 \index{CpvAccess}
115
116 Macros for thread-private variables:
117 \begin{verbatim}
118 CtvDeclare(type,variable)
119 CtvStaticDeclare(type,variable)
120 CtvExtern(type,variable)
121 CtvInitialize(type,variable)
122 CtvAccess(variable)
123 \end{verbatim}
124 \index{CtvDeclare}
125 \index{CtvStaticDeclare}
126 \index{CtvExtern}
127 \index{CtvInitialize}
128 \index{CtvAccess}
129
130
131 A sample code to illustrate the usage of the macros is provided
132 in Figure~\ref{fig:cpv}.
133 There are a few rules that user must pay attention: The
134 {\tt type} and {\tt variable} fields of the macros must be a single
135 word. Therefore, structures or pointer types can be used by defining
136 new types with the {\tt typedef}. In the sample code, for example,
137 a {\tt struct point} type is redefined with a {\tt typedef} as {\tt Point}
138 in order to use it in the macros. Similarly,  the access macros contain
139 only the name of the global variable. Any indexing or member access
140 must be outside of the macro as shown in the sample code 
141 (function {\tt func1}). Finally, all the global variables must be
142 installed before they are used. One way to do this systematically is
143 to provide a module-init function for each file (in the sample code - 
144 {\tt ModuleInit()}. The module-init functions of each file, then, can be 
145 called at the beginning of execution to complete the installations of 
146 all global variables.
147
148 \begin{figure}
149 \begin{verbatim}
150 File Module1.c
151
152     typedef struct point
153     {
154          float x,y;
155     } Point;
156
157
158     CpvDeclare(int, a);
159     CpvDeclare(Point, p);
160
161     void ModuleInit()
162     {
163          CpvInitialize(int, a)
164          CpvInitialize(Point, p);
165
166          CpvAccess(a) = 0;
167     }
168
169     int func1() 
170     {
171          CpvAccess(p).x = 0;
172          CpvAccess(p).y = CpvAccess(p).x + 1;
173     }
174 \end{verbatim}
175 \caption{An example code for global variable usage}
176 \label{fig:cpv}
177 \end{figure}
178
179 \section{Utility Functions}
180 \label{utility}
181
182 To further simplify programming with global variables on shared memory machines,
183 Converse provides following functions and/or macros. \note{These functions
184 are defined on machines other than shared-memory machines also, and
185 have the effect of only one processor per node and only one thread per 
186 processor.}
187
188 \function{int CmiMyRank()}
189 \index{CmiMyRank}
190 \desc{Returns the rank of the calling processor within a shared memory node.}
191
192 \function{void CmiNodeBarrier()}
193 \index{CmiNodeBarrier}
194 \desc{Provide barrier synchronization at the node level, i.e. all the 
195 processors belonging to the node participate in this barrier.}
196
197 \function{void *CmiSvAlloc(int size)}
198 \index{CmiSvAlloc}
199 \desc{Allocates a block of memory of \param{size} bytes from the heap in node's 
200 local memory and returns pointer to the start of this block. \note{On 
201 machines other than shared-memory machines, this is equivalent to 
202 \param{CmiAlloc}.}}