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