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