\documentclass[10pt]{article}
\usepackage{../pplmanual}
\usepackage{xspace}
\renewcommand{\jade}{Jade\xspace}
\input{../pplmanual}


\title{Jade Language Manual}
\version{1.0}
\credits{
Jade was developed by Jayant DeSouza.
}

\begin{document}
\maketitle

\section{Introduction}

This manual describes \jade, which is a new parallel programming language
developed over \charmpp{} and Java. \charmpp{} is a
\CC{}-based parallel programming library developed by Prof. L. V. Kal\'{e} 
and his students over the last 10 years at University of Illinois.

We first describe our philosophy behind this work (why we do what we do).
Later we give a brief introduction to \charmpp{} and rationale for \jade. We
describe \jade in detail. Appendices contain the details of installing
\jade, building and running \jade programs.

\subsection{Our Philosophy}

\subsection{Terminology}

\begin{description}

\item[Module] A module refers to 

\item[Thread] A thread is a lightweight process that owns a stack and machine
registers including program counter, but shares code and data with other
threads within the same address space. If the underlying operating system
recognizes a thread, it is known as kernel thread, otherwise it is known as
user-thread. A context-switch between threads refers to suspending one thread's
execution and transferring control to another thread. Kernel threads typically
have higher context switching costs than user-threads because of operating
system overheads. The policy implemented by the underlying system for
transferring control between threads is known as thread scheduling policy.
Scheduling policy for kernel threads is determined by the operating system, and
is often more inflexible than user-threads. Scheduling policy is said to be
non-preemptive if a context-switch occurs only when the currently running
thread willingly asks to be suspended, otherwise it is said to be preemptive.
\jade threads are non-preemptive user-level threads.

\item[Object] An object is just a blob of memory on which certain computations
can be performed. The memory is referred to as an object's state, and the set
of computations that can be performed on the object is called the interface of
the object.

\end{description}

\section{\charmpp{}}

\charmpp{} is an object-oriented parallel programming library for \CC{}.  It
differs from traditional message passing programming libraries (such as MPI) in
that \charmpp{} is ``message-driven''. Message-driven parallel programs do not
block the processor waiting for a message to be received.  Instead, each
message carries with itself a computation that the processor performs on
arrival of that message. The underlying runtime system of \charmpp{} is called
\converse{}, which implements a ``scheduler'' that chooses which message to
schedule next (message-scheduling in \charmpp{} involves locating the object
for which the message is intended, and executing the computation specified in
the incoming message on that object). A parallel object in \charmpp{} is a
\CC{} object on which a certain computations can be asked to performed from
remote processors.

\charmpp{} programs exhibit latency tolerance since the scheduler always picks
up the next available message rather than waiting for a particular message to
arrive.  They also tend to be modular, because of their object-based nature.
Most importantly, \charmpp{} programs can be \emph{dynamically load balanced},
because the messages are directed at objects and not at processors; thus
allowing the runtime system to migrate the objects from heavily loaded
processors to lightly loaded processors. It is this feature of \charmpp{} that
we utilize for \jade.

Since many CSE applications are originally written using MPI, one would have to
do a complete rewrite if they were to be converted to \charmpp{} to take
advantage of dynamic load balancing. This is indeed impractical. However,
\converse{} -- the runtime system of \charmpp{} -- came to our rescue here,
since it supports interoperability between different parallel programming
paradigms such as parallel objects and threads. Using this feature, we
developed \jade, an implementation of a significant subset of MPI-1.1
standard over \charmpp{}.  \jade is described in the next section.

\section{\jade}

Every mainchare's main is executed at startup.

\subsection{threaded methods}

\begin{alltt}
class C {
    public threaded void start(CProxy_CacheGroup cg) { ... }
}
\end{alltt}

\subsection{readonly}

\begin{alltt}
class C {
    public static readonly CProxy_TheMain mainChare;
    public static int readonly aReadOnly;
}
\end{alltt}

Accessed as C.aReadOnly;

Must be initialized in the main of a mainchare.  Value at the end of main is
propagated to all processors.  Then execution begins.

\subsection{msa}

\begin{alltt}
arr1.enroll();
int a = arr1[10]; // get
arr1[10] = 122; // set
arr1[10] += 2;  // accumulate
arr1.sync();    // sync
\end{alltt}

\subsection{\jade Status}

\appendix

\section{Installing \jade}

\jade is included in the source distribution of \charmpp{}. 
To get the latest sources from PPL, visit:
	http://charm.cs.uiuc.edu/

and follow the download link.
Now one has to build \charmpp{} and \jade from source.

The build script for \charmpp{} is called \texttt{build}. The syntax for this
script is:

\begin{alltt}
> build <target> <version> <opts>
\end{alltt}

For building \jade (which also includes building \charmpp{} and other
libraries needed by \jade), specify \verb+<target>+ to be \verb+jade+. And
\verb+<opts>+ are command line options passed to the \verb+charmc+ compile
script.  Common compile time options such as \texttt{-g, -O, -Ipath, -Lpath,
-llib} are accepted. 

To build a debugging version of \jade, use the option: ``\texttt{-g}''. 
To build a production version of \jade, use the options: ``\texttt{-O 
-DCMK\_OPTIMIZE=1}''.

\verb+<version>+ depends on the machine, operating system, and the underlying
communication library one wants to use for running \jade programs.
See the charm/README file for details on picking the proper version.
Following is an example of how to build \jade under linux and ethernet
environment, with debugging info produced:

\begin{alltt}
> build jade net-linux -g
\end{alltt}

\section{Compiling and Running \jade Programs}
\subsection{Compiling \jade Programs}

\charmpp{} provides a cross-platform compile-and-link script called \charmc{}
to compile C, \CC{}, Fortran, \charmpp{} and \jade programs.  This script
resides in the \texttt{bin} subdirectory in the \charmpp{} installation
directory. The main purpose of this script is to deal with the differences of
various compiler names and command-line options across various machines on
which \charmpp{} runs.

In spite of the platform-neutral syntax of \charmc{}, one may have to specify
some platform-specific options for compiling and building \jade codes.
Fortunately, if \charmc{} does not recognize any particular options on its
command line, it promptly passes it to all the individual compilers and linkers
it invokes to compile the program.

You can use \charmc{} to build your \jade program the same way as other
compilers like \texttt{cc}.  To build an \jade program, the command line 
option \emph{-language jade} should be specified. All the command line 
flags that you would use for other compilers can be used with \charmc the 
same way. For example:

\begin{alltt}
> charmc -language jade -c pgm.java -O3
> charmc -language jade -o pgm pgm.o -lm -O3 
\end{alltt}

\subsection{Running}

The \charmpp{} distribution contains a script called \texttt{charmrun} that makes
the job of running \jade programs portable and easier across all parallel
machines supported by \charmpp{}. When compiling a \jade program, \charmc{} copies \texttt{charmrun} to the directory
where the \jade program is built.  \texttt{charmrun} takes a command line
parameter specifying the number of processors to run on, and the name of the program
followed by \jade options (such as TBD) and the program arguments. A typical
invocation of \jade program \texttt{pgm} with \texttt{charmrun} is:

\begin{alltt}
> charmrun pgm +p16 +vp32 +tcharm_stacksize 3276800
\end{alltt}

Here, the \jade program \texttt{pgm} is run on 16 physical processors with
32 chunks (which will be mapped 2 per processor initially), where each
user-level thread associated with a chunk has the stack size of 3,276,800 bytes.

\section{Jade Developer documentation}

\subsection{Files}

\jade source files are spread out across several directories of the \charmpp{}
CVS tree.

\begin{tabular}{|r|l|}
\hline\\
charm/doc/jade                         & \jade user documentation files \\
charm/src/langs/jade/                  & ANTLR parser files, \jade runtime library code\\
charm/java/charm/jade/                 & \jade java code \\
charm/java/bin/                        & \jade scripts \\
charm/pgms/jade/                       & \jade example programs and tests \\
\hline
\end{tabular}

After building \jade, files are installed in:

\begin{tabular}{|r|l|}
\hline\\
charm/include/                         & \jade runtime library header files\\
charm/lib/                             & \jade runtime library\\
charm/java/bin/                        & \texttt{jade.jar} file \\
\hline
\end{tabular}

\subsection{Java packages}

The way packages work in Java is as follows: There is a ROOT directory. Within
the ROOT, a subdirectory is used which also gives the package name.  Beneath
the package directory all the \texttt{.class} files are stored.  The ROOT
directory should be placed in the java CLASSPATH.

For \jade, the ROOT is charm/java/charm/.

The \jade package name is \texttt{jade}, and is in charm/java/charm/jade.
Within here, all the jade Java files are placed, they are compiled to
\texttt{.class} files, and then jar'd up into the \texttt{jade.jar} file, which
is placed in charm/java/bin for convenience.

\end{document}
