Added multicast.
[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.9  1997-07-29 20:55:30  milind
16 % Updated machine model chapter and merged it with Cmi chapter.
17 %
18 % Revision 1.8  1997/07/19 23:51:52  wilmarth
19 % Several changes to correct/clarify test were made.
20 %
21 % Revision 1.7  1997/06/26 05:16:22  jyelon
22 % Still improving manual.
23 %
24 % Revision 1.6  1997/06/25 06:53:48  jyelon
25 % Just trying to make this whole manual make more sense.
26 %
27 % Revision 1.5  1995/11/16 22:11:11  milind
28 % removed hardwired reference.
29 %
30 % Revision 1.4  1995/11/01  21:16:23  milind
31 % Added index entries.
32 %
33 % Revision 1.3  1995/10/30  17:33:54  milind
34 % Changed Cth variables macros to Ctv macros.
35 % Added "More on Shared Memory Machines" section.
36 %
37 % Revision 1.2  1995/10/27  21:02:54  milind
38 % Integrated into Manual.
39 %
40 % Revision 1.1  1995/10/26  21:08:23  gursoy
41 % Initial revision
42 %
43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
44
45 \section{Global Variables and Utility functions}
46 \label{globalvars}
47
48 Different vendors are not consistent about how they treat global and static
49 variables.  Most vendors write C compilers in which global variables are
50 shared among all the processors in the node.  A few vendors write C
51 compilers where each processor has its own copy of the global variables.
52 In theory, it would also be possible to design the compiler so that
53 each thread has its own copy of the global variables.
54
55 The lack of consistency across vendors, makes it very hard to write a
56 portable program.  The fact that most vendors make the globals shared
57 is inconvenient as well, usually, you don't want your globals to be
58 shared.  For these reasons, we added ``pseudoglobals'' to Converse.
59 These act much like C global and static variables, except that you have
60 explicit control over the degree of sharing.
61
62 \subsection{Converse PseudoGlobals}
63
64 Three classes of pseudoglobal variables are supported: node-private,
65 process-private, and thread-private variables.
66
67 \begin{description}
68 \item[Node-private global variables] are specific to a node. They are
69      shared among all the processes within the node.
70 \item[Process-private global variables]  are specific to a process. They are
71      shared among all the threads within the process.
72 \item[Thread-private global variables] are specific to a thread. They are 
73      truely private.
74 \end{description}
75
76 There are five macros for each class. These macros are for
77 declaration, static declaration, extern declaration, initialization,
78 and access. The declaration, static and extern specifications have the
79 same meaning as in C. In order to support portability, however, the
80 global variables must be installed properly, by using the
81 initialization macros.  For example, if the underlying machine is a
82 simulator for the machine model supported by Converse, then the
83 thread-private variables must be turned into arrays of variables.
84 Initialize and Access macros hide these details from the user.  It is
85 possible to use global variables without these macros, as supported by
86 the underlying machine, but at the expense of portability.
87
88 Macros for node-private variables:
89 \begin{verbatim}
90 CsvDeclare(type,variable)
91 CsvStaticDeclare(type,variable)
92 CsvExtern(type,variable)
93 CsvInitialize(type,variable)
94 CsvAccess(variable)
95 \end{verbatim}
96
97 \index{CsvDeclare}
98 \index{CsvStaticDeclare}
99 \index{CsvExtern}
100 \index{CsvInitialize}
101 \index{CsvAccess}
102
103 Macros for process-private variables:
104 \begin{verbatim}
105 CpvDeclare(type,variable)
106 CpvStaticDeclare(type,variable)
107 CpvExtern(type,variable)
108 CpvInitialize(type,variable)
109 CpvAccess(variable)
110 \end{verbatim}
111 \index{CpvDeclare}
112 \index{CpvStaticDeclare}
113 \index{CpvExtern}
114 \index{CpvInitialize}
115 \index{CpvAccess}
116
117 Macros for thread-private variables:
118 \begin{verbatim}
119 CtvDeclare(type,variable)
120 CtvStaticDeclare(type,variable)
121 CtvExtern(type,variable)
122 CtvInitialize(type,variable)
123 CtvAccess(variable)
124 \end{verbatim}
125 \index{CtvDeclare}
126 \index{CtvStaticDeclare}
127 \index{CtvExtern}
128 \index{CtvInitialize}
129 \index{CtvAccess}
130
131
132 A sample code to illustrate the usage of the macros is provided
133 in Figure~\ref{fig:cpv}.
134 There are a few rules that the user must pay attention to: The
135 {\tt type} and {\tt variable} fields of the macros must be a single
136 word. Therefore, structures or pointer types can be used by defining
137 new types with the {\tt typedef}. In the sample code, for example,
138 a {\tt struct point} type is redefined with a {\tt typedef} as {\tt Point}
139 in order to use it in the macros. Similarly,  the access macros contain
140 only the name of the global variable. Any indexing or member access
141 must be outside of the macro as shown in the sample code 
142 (function {\tt func1}). Finally, all the global variables must be
143 installed before they are used. One way to do this systematically is
144 to provide a module-init function for each file (in the sample code - 
145 {\tt ModuleInit()}. The module-init functions of each file, then, can be 
146 called at the beginning of execution to complete the installations of 
147 all global variables.
148
149 \begin{figure}
150 \begin{verbatim}
151 File Module1.c
152
153     typedef struct point
154     {
155          float x,y;
156     } Point;
157
158
159     CpvDeclare(int, a);
160     CpvDeclare(Point, p);
161
162     void ModuleInit()
163     {
164          CpvInitialize(int, a)
165          CpvInitialize(Point, p);
166
167          CpvAccess(a) = 0;
168     }
169
170     int func1() 
171     {
172          CpvAccess(p).x = 0;
173          CpvAccess(p).y = CpvAccess(p).x + 1;
174     }
175 \end{verbatim}
176 \caption{An example code for global variable usage}
177 \label{fig:cpv}
178 \end{figure}
179
180 \subsection{Utility Functions}
181 \label{utility}
182
183 To further simplify programming with global variables on shared memory
184 machines, Converse provides the following functions and/or
185 macros. \note{These functions are defined on machines other than
186 shared-memory machines also, and have the effect of only one processor
187 per node and only one thread per processor.}
188
189 \function{int CmiMyNode()}
190 \index{CmiMyNode}
191 \desc{Returns the node number to which the calling processor belongs.}
192
193 \function{int CmiNumNodes()}
194 \index{CmiNumNodes}
195 \desc{Returns number of nodes in the system. Note that this is not the
196 same as \param{CmiNumPes()}.}
197
198 \function{int CmiMyRank()}
199 \index{CmiMyRank}
200 \desc{Returns the rank of the calling processor within a shared memory node.}
201
202 \function{int CmiNodeFirst(int node)}
203 \index{CmiNodeFirst}
204 \desc{Returns the processor number of the lowest ranked processor on node
205 \param{node}}
206
207 \function{int CmiNodeSize(int node)}
208 \index{CmiNodeSize}
209 \desc{Returns the number of processors that belong to the node \param{node}.}
210
211 \function{int CmiNodeOf(int pe)}
212 \index{CmiNodeOf}
213 \desc{Returns the node number to which processor \param{pe} belongs. Indeed,
214 \param{CmiMyNode()} is a utility macro that is aliased to 
215 \param{CmiNodeOf(CmiMyPe())}.}
216
217 \function{int CmiRankOf(int pe)}
218 \index{CmiRankOf}
219 \desc{Returns the rank of processor \param{pe} in the node to which it belongs.}
220
221 \subsection{Node-level Locks and other Synchronization Mechanisms}
222 \label{nodelocks}
223
224 \function{void CmiNodeBarrier()}
225 \index{CmiNodeBarrier}
226 \desc{Provide barrier synchronization at the node level, i.e. all the 
227 processors belonging to the node participate in this barrier.}
228
229 \function{typedef McDependentType CmiNodeLock}
230 \index{CmiNodeLock}
231 \desc{This is the type for all the node-level locks in Converse.}
232
233 \function{CmiNodeLock CmiCreateLock(void)}
234 \index{CmiCreateLock}
235 \desc{Creates, initializes and returns a new lock. Initially the
236 lock is unlocked.}
237
238 \function{void CmiLock(CmiNodeLock lock)}
239 \index{CmiLock}
240 \desc{Locks \param{lock}. If the \param{lock} has been locked by other
241 processor, waits for \param{lock} to be unlocked.}
242
243 \function{void CmiUnlock(CmiNodeLock lock)}
244 \index{CmiUnlock}
245 \desc{Unlocks \param{lock}. Processors waiting for the \param{lock} can
246 then compete for acquiring \param{lock}.}
247
248 \function{int CmiTryLock(CmiNodeLock lock)}
249 \index{CmiTryLock}
250 \desc{Tries to lock \param{lock}. If it succeeds in locking, it returns
251 0. If any other processor has already acquired the lock, it returns 1.}
252
253 \function{voi CmiDestroyLock(CmiNodeLock lock)}
254 \index{CmiDestroyLock}
255 \desc{Frees any memory associated with \param{lock}. It is an error to
256 perform any operations with \param{lock} after a call to this function.}
257
258 \function{void *CmiSvAlloc(int size)}
259 \index{CmiSvAlloc}
260 \desc{Allocates a block of memory of \param{size} bytes from the heap in node's 
261 local memory and returns pointer to the start of this block. \note{On 
262 machines other than shared-memory machines, this is equivalent to 
263 \param{CmiAlloc}.}}