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