5ac0b95d59c87801d9b460226186a4dade1ad9f1
[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.5  1995-11-16 22:11:11  milind
16 % removed hardwired reference.
17 %
18 % Revision 1.4  1995/11/01  21:16:23  milind
19 % Added index entries.
20 %
21 % Revision 1.3  1995/10/30  17:33:54  milind
22 % Changed Cth variables macros to Ctv macros.
23 % Added "More on Shared Memory Machines" section.
24 %
25 % Revision 1.2  1995/10/27  21:02:54  milind
26 % Integrated into Manual.
27 %
28 % Revision 1.1  1995/10/26  21:08:23  gursoy
29 % Initial revision
30 %
31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32
33 \chapter{Machine Model and Global Variables}
34
35
36 The machine model assumed by Converse consists of a collection of
37 nodes, where each node comprises of a number of processors that
38 share memory. In addition, each of the processors could have multiple
39 threads running on them which share code and data but have different
40 stacks. On networks of workstations or distributed memory MIMD
41 machines, number of processors in each node is assumed to be one and on
42 machines that do not have native thread support, there is only one
43 thread per processor. Converse provides functions to determine rank of
44 a processor within a node and a consistent access/modification
45 mechanism to manipulate global variables.
46
47 \section{Global Variables}
48
49 Global variables are allowed in Converse via specific macros.  These macros 
50 ensure that the program runs portably on various parallel machines. 
51 Three classes of global variables are supported: node-private,
52 process-private, and thread-private variables. 
53
54 \begin{description}
55 \item[Node-private global variables] are specific to a node. They are
56      shared among all the processes within the node.
57 \item[Process-private global variables]  are specific to a process. They are
58      shared among all the threads within the process.
59 \item[Thread-private global variables] are specific to a thread. They are 
60      truely private.
61 \end{description}
62
63 There are five macros for each class. These macros are for
64 declaration, static declaration, extern declaration, initialization, and
65 access. The declaration, static and extern specifications have the same
66 meaning as in C. In order to support portability, however, the global
67 variables must be installed properly, by using the initialization macros.
68 For example, if the underlying machine is a simulator for the machine model 
69 supported by Converse, then the thread-private variables must be turned into 
70 arrays of variables.  Initialize and Access macros hide these details from 
71 the user.  It is possible to use global variables without these macros, 
72 as supported by the underlying machine, but at the expense of portability.
73
74
75 Macros for node-private variables:
76 \begin{verbatim}
77 CsvDeclare(type,variable)
78 CsvStaticDeclare(type,variable)
79 CsvExtern(type,variable)
80 CsvInitialize(type,variable)
81 CsvAccess(variable)
82 \end{verbatim}
83
84 \index{CsvDeclare}
85 \index{CsvStaticDeclare}
86 \index{CsvExtern}
87 \index{CsvInitialize}
88 \index{CsvAccess}
89
90 Macros for process-private variables:
91 \begin{verbatim}
92 CpvDeclare(type,variable)
93 CpvStaticDeclare(type,variable)
94 CpvExtern(type,variable)
95 CpvInitialize(type,variable)
96 CpvAccess(variable)
97 \end{verbatim}
98 \index{CpvDeclare}
99 \index{CpvStaticDeclare}
100 \index{CpvExtern}
101 \index{CpvInitialize}
102 \index{CpvAccess}
103
104 Macros for thread-private variables:
105 \begin{verbatim}
106 CtvDeclare(type,variable)
107 CtvStaticDeclare(type,variable)
108 CtvExtern(type,variable)
109 CtvInitialize(type,variable)
110 CtvAccess(variable)
111 \end{verbatim}
112 \index{CtvDeclare}
113 \index{CtvStaticDeclare}
114 \index{CtvExtern}
115 \index{CtvInitialize}
116 \index{CtvAccess}
117
118
119 \subsection{Example of Usage}
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}.}}