deleted package xspace form default inclusion into pplmanual manuals.
[charm.git] / doc / jade / manual.tex
1 \documentclass[10pt]{article}
2 \usepackage{../pplmanual}
3 \usepackage{xspace}
4 \renewcommand{\jade}{Jade\xspace}
5 \input{../pplmanual}
6
7
8 \title{Jade Language Manual}
9 \version{1.0}
10 \credits{
11 Jade was developed by Jayant DeSouza.
12 }
13
14 \begin{document}
15 \maketitle
16
17 \section{Introduction}
18
19 This manual describes \jade, which is a new parallel programming language
20 developed over \charmpp{} and Java. \charmpp{} is a
21 \CC{}-based parallel programming library developed by Prof. L. V. Kal\'{e} 
22 and his students over the last 10 years at University of Illinois.
23
24 We first describe our philosophy behind this work (why we do what we do).
25 Later we give a brief introduction to \charmpp{} and rationale for \jade. We
26 describe \jade in detail. Appendices contain the details of installing
27 \jade, building and running \jade programs.
28
29 \subsection{Our Philosophy}
30
31 \subsection{Terminology}
32
33 \begin{description}
34
35 \item[Module] A module refers to 
36
37 \item[Thread] A thread is a lightweight process that owns a stack and machine
38 registers including program counter, but shares code and data with other
39 threads within the same address space. If the underlying operating system
40 recognizes a thread, it is known as kernel thread, otherwise it is known as
41 user-thread. A context-switch between threads refers to suspending one thread's
42 execution and transferring control to another thread. Kernel threads typically
43 have higher context switching costs than user-threads because of operating
44 system overheads. The policy implemented by the underlying system for
45 transferring control between threads is known as thread scheduling policy.
46 Scheduling policy for kernel threads is determined by the operating system, and
47 is often more inflexible than user-threads. Scheduling policy is said to be
48 non-preemptive if a context-switch occurs only when the currently running
49 thread willingly asks to be suspended, otherwise it is said to be preemptive.
50 \jade threads are non-preemptive user-level threads.
51
52 \item[Object] An object is just a blob of memory on which certain computations
53 can be performed. The memory is referred to as an object's state, and the set
54 of computations that can be performed on the object is called the interface of
55 the object.
56
57 \end{description}
58
59 \section{\charmpp{}}
60
61 \charmpp{} is an object-oriented parallel programming library for \CC{}.  It
62 differs from traditional message passing programming libraries (such as MPI) in
63 that \charmpp{} is ``message-driven''. Message-driven parallel programs do not
64 block the processor waiting for a message to be received.  Instead, each
65 message carries with itself a computation that the processor performs on
66 arrival of that message. The underlying runtime system of \charmpp{} is called
67 \converse{}, which implements a ``scheduler'' that chooses which message to
68 schedule next (message-scheduling in \charmpp{} involves locating the object
69 for which the message is intended, and executing the computation specified in
70 the incoming message on that object). A parallel object in \charmpp{} is a
71 \CC{} object on which a certain computations can be asked to performed from
72 remote processors.
73
74 \charmpp{} programs exhibit latency tolerance since the scheduler always picks
75 up the next available message rather than waiting for a particular message to
76 arrive.  They also tend to be modular, because of their object-based nature.
77 Most importantly, \charmpp{} programs can be \emph{dynamically load balanced},
78 because the messages are directed at objects and not at processors; thus
79 allowing the runtime system to migrate the objects from heavily loaded
80 processors to lightly loaded processors. It is this feature of \charmpp{} that
81 we utilize for \jade.
82
83 Since many CSE applications are originally written using MPI, one would have to
84 do a complete rewrite if they were to be converted to \charmpp{} to take
85 advantage of dynamic load balancing. This is indeed impractical. However,
86 \converse{} -- the runtime system of \charmpp{} -- came to our rescue here,
87 since it supports interoperability between different parallel programming
88 paradigms such as parallel objects and threads. Using this feature, we
89 developed \jade, an implementation of a significant subset of MPI-1.1
90 standard over \charmpp{}.  \jade is described in the next section.
91
92 \section{\jade}
93
94 Every mainchare's main is executed at startup.
95
96 \subsection{threaded methods}
97
98 \begin{alltt}
99 class C {
100     public threaded void start(CProxy_CacheGroup cg) { ... }
101 }
102 \end{alltt}
103
104 \subsection{readonly}
105
106 \begin{alltt}
107 class C {
108     public static readonly CProxy_TheMain mainChare;
109     public static int readonly aReadOnly;
110 }
111 \end{alltt}
112
113 Accessed as C.aReadOnly;
114
115 Must be initialized in the main of a mainchare.  Value at the end of main is
116 propagated to all processors.  Then execution begins.
117
118 \subsection{msa}
119
120 \begin{alltt}
121 arr1.enroll();
122 int a = arr1[10]; // get
123 arr1[10] = 122; // set
124 arr1[10] += 2;  // accumulate
125 arr1.sync();    // sync
126 \end{alltt}
127
128 \subsection{\jade Status}
129
130 \appendix
131
132 \section{Installing \jade}
133
134 \jade is included in the source distribution of \charmpp{}. 
135 To get the latest sources from PPL, visit:
136         http://charm.cs.uiuc.edu/
137
138 and follow the download link.
139 Now one has to build \charmpp{} and \jade from source.
140
141 The build script for \charmpp{} is called \texttt{build}. The syntax for this
142 script is:
143
144 \begin{alltt}
145 > build <target> <version> <opts>
146 \end{alltt}
147
148 For building \jade (which also includes building \charmpp{} and other
149 libraries needed by \jade), specify \verb+<target>+ to be \verb+jade+. And
150 \verb+<opts>+ are command line options passed to the \verb+charmc+ compile
151 script.  Common compile time options such as \texttt{-g, -O, -Ipath, -Lpath,
152 -llib} are accepted. 
153
154 To build a debugging version of \jade, use the option: ``\texttt{-g}''. 
155 To build a production version of \jade, use the options: ``\texttt{-O 
156 -DCMK\_OPTIMIZE=1}''.
157
158 \verb+<version>+ depends on the machine, operating system, and the underlying
159 communication library one wants to use for running \jade programs.
160 See the charm/README file for details on picking the proper version.
161 Following is an example of how to build \jade under linux and ethernet
162 environment, with debugging info produced:
163
164 \begin{alltt}
165 > build jade net-linux -g
166 \end{alltt}
167
168 \section{Compiling and Running \jade Programs}
169 \subsection{Compiling \jade Programs}
170
171 \charmpp{} provides a cross-platform compile-and-link script called \charmc{}
172 to compile C, \CC{}, Fortran, \charmpp{} and \jade programs.  This script
173 resides in the \texttt{bin} subdirectory in the \charmpp{} installation
174 directory. The main purpose of this script is to deal with the differences of
175 various compiler names and command-line options across various machines on
176 which \charmpp{} runs.
177
178 In spite of the platform-neutral syntax of \charmc{}, one may have to specify
179 some platform-specific options for compiling and building \jade codes.
180 Fortunately, if \charmc{} does not recognize any particular options on its
181 command line, it promptly passes it to all the individual compilers and linkers
182 it invokes to compile the program.
183
184 You can use \charmc{} to build your \jade program the same way as other
185 compilers like \texttt{cc}.  To build an \jade program, the command line 
186 option \emph{-language jade} should be specified. All the command line 
187 flags that you would use for other compilers can be used with \charmc the 
188 same way. For example:
189
190 \begin{alltt}
191 > charmc -language jade -c pgm.java -O3
192 > charmc -language jade -o pgm pgm.o -lm -O3 
193 \end{alltt}
194
195 \subsection{Running}
196
197 The \charmpp{} distribution contains a script called \texttt{charmrun} that makes
198 the job of running \jade programs portable and easier across all parallel
199 machines supported by \charmpp{}. When compiling a \jade program, \charmc{} copies \texttt{charmrun} to the directory
200 where the \jade program is built.  \texttt{charmrun} takes a command line
201 parameter specifying the number of processors to run on, and the name of the program
202 followed by \jade options (such as TBD) and the program arguments. A typical
203 invocation of \jade program \texttt{pgm} with \texttt{charmrun} is:
204
205 \begin{alltt}
206 > charmrun pgm +p16 +vp32 +tcharm_stacksize 3276800
207 \end{alltt}
208
209 Here, the \jade program \texttt{pgm} is run on 16 physical processors with
210 32 chunks (which will be mapped 2 per processor initially), where each
211 user-level thread associated with a chunk has the stack size of 3,276,800 bytes.
212
213 \section{Jade Developer documentation}
214
215 \subsection{Files}
216
217 \jade source files are spread out across several directories of the \charmpp{}
218 CVS tree.
219
220 \begin{tabular}{|r|l|}
221 \hline\\
222 charm/doc/jade                         & \jade user documentation files \\
223 charm/src/langs/jade/                  & ANTLR parser files, \jade runtime library code\\
224 charm/java/charm/jade/                 & \jade java code \\
225 charm/java/bin/                        & \jade scripts \\
226 charm/pgms/jade/                       & \jade example programs and tests \\
227 \hline
228 \end{tabular}
229
230 After building \jade, files are installed in:
231
232 \begin{tabular}{|r|l|}
233 \hline\\
234 charm/include/                         & \jade runtime library header files\\
235 charm/lib/                             & \jade runtime library\\
236 charm/java/bin/                        & \texttt{jade.jar} file \\
237 \hline
238 \end{tabular}
239
240 \subsection{Java packages}
241
242 The way packages work in Java is as follows: There is a ROOT directory. Within
243 the ROOT, a subdirectory is used which also gives the package name.  Beneath
244 the package directory all the \texttt{.class} files are stored.  The ROOT
245 directory should be placed in the java CLASSPATH.
246
247 For \jade, the ROOT is charm/java/charm/.
248
249 The \jade package name is \texttt{jade}, and is in charm/java/charm/jade.
250 Within here, all the jade Java files are placed, they are compiled to
251 \texttt{.class} files, and then jar'd up into the \texttt{jade.jar} file, which
252 is placed in charm/java/bin for convenience.
253
254 \end{document}