Charj Manual: adding a preliminary version of manual
authorBilge Acun <acun2@illinois.edu>
Fri, 14 Dec 2012 09:09:47 +0000 (03:09 -0600)
committerBilge Acun <acun2@illinois.edu>
Fri, 14 Dec 2012 09:12:41 +0000 (03:12 -0600)
doc/Makefile
doc/charj/Makefile [new file with mode: 0644]
doc/charj/fig/fig0.png [new file with mode: 0644]
doc/charj/fig/fig1.png [new file with mode: 0644]
doc/charj/manual.tex [new file with mode: 0644]

index 98efdc8ecd5d696c042ce2db5e21f561cf7039bd..140c2c4ed0c001c73a8da33f562d2ee4463e95d7 100644 (file)
@@ -4,7 +4,7 @@ RMCMD   = rm -f ./pplmanual.sty
 WEBDIR = /www/manuals
 DIRS   = converse convext charm++ libraries f90charm charisma pose \
        fem ifem netfem ampi bigsim mblock projections tcharm debugger faq \
-       bignetsim
+       bignetsim charj
 
 all: pdf ps html
 
diff --git a/doc/charj/Makefile b/doc/charj/Makefile
new file mode 100644 (file)
index 0000000..c234e21
--- /dev/null
@@ -0,0 +1,12 @@
+# Stub makefile for LaTeX PPL manual
+FILE=manual
+TEX=$(FILE).tex 
+
+DEST=charj
+LATEX2HTML=$(L2H) -split 5
+DOCTITLE='Charj'
+
+include ../Makefile.common
+
+index.tex:
+       touch index.tex
diff --git a/doc/charj/fig/fig0.png b/doc/charj/fig/fig0.png
new file mode 100644 (file)
index 0000000..e41c860
Binary files /dev/null and b/doc/charj/fig/fig0.png differ
diff --git a/doc/charj/fig/fig1.png b/doc/charj/fig/fig1.png
new file mode 100644 (file)
index 0000000..c07641a
Binary files /dev/null and b/doc/charj/fig/fig1.png differ
diff --git a/doc/charj/manual.tex b/doc/charj/manual.tex
new file mode 100644 (file)
index 0000000..3ade8df
--- /dev/null
@@ -0,0 +1,151 @@
+\documentclass[11pt]{article}
+\usepackage{../pplmanual}
+\input{../pplmanual}
+
+\makeindex
+
+\title{Charj Manual \\ Compiler Support for Productive Parallel Programming \footnote{last modified 12/14/2012 by Bilge Acun}}
+\version{1.0}
+\begin{document}
+
+\maketitle
+
+\section{Introduction}
+
+Charj is a new programming language which incorporates syntax, semantic analysis, and optimization targeted at HPC code with its associated compiler. 
+
+\begin{figure}[h]
+\begin{center}
+\includegraphics[width=4in]{fig/fig0.png}
+\end{center}
+\caption{Charj}
+\label{fig:fig0}
+\end{figure}
+
+With Charj, we aim to allow programmers to achieve the performance associated with carefully written, hand-optimized Charm++ applications, but with much less time and effort. If effect, we hope to combine the productivity that programmers experience when writing relatively simple, naive applications while enjoying performance that would normally require a much greater investment of time, effort, and expertise. 
+
+Charj compiler takes Charj codes as input and produces Charm++ interface (.ci) and C++ code (.C and .h) as an output. 
+
+\begin{figure}[h]
+\begin{center}
+\includegraphics[width=4in]{fig/fig1.png}
+\end{center}
+\caption{Compilation process for Charj application}
+\label{fig:fig1}
+\end{figure}
+
+\begin{verbatim}
+
+
+\end{verbatim}
+
+To make use of Charj;
+\begin{enumerate}
+\item Build Charm++, then build Charj
+\item Write your Charj program
+\item Compile and run it!
+\end{enumerate}
+
+\section{Building, Compiling and Running}
+{\bf To write a program and compile with Charj:}
+
+\begin{enumerate}
+\item Go to: {\it charm/src/langs/charj} and {\it "make" } (Assuming Charm++ is already installed)
+\item Write your Charj code in a file with {\it .cj} extension. {\it (SampleProgram.cj)}
+\item Execute {\it charjc} script on the file {\it SampleProgram.cj}: \\ {\it charm/src/langs/charj/bin/charjc  SampleProgram.cj}
+\item After execution, a folder named {\it“SampleProgram.cj.gen”} will be created in the directory of {\it SampleProgram.cj}. This folder will contain the emitted Charm++ files; {\it SampleProgram.ci, SampleProgram.h SampleProgram.cc }.
+
+* Example Charj programs can be found at {\it charm/src/langs/charj/tests}
+\end{enumerate}
+
+
+\section{Writing a Charj Program}
+
+\subsection{General structure of a Charj program; }
+
+\begin{verbatim}
+
+       readonly Main@ mainProxy;       //readonly proxy type
+       readonly int value;                     //readonly variable
+       
+       public mainchare Main {
+           public entry Main(CkArgMsg[~]@ m){...}      //Main constructor
+           public entry void done(){...}                       //entry method 
+           private int localMethod(int value){...}     //non-entry method
+       }
+       public chare_array [1d] SampleChareArray1d{...} //1d chare array
+       public chare_array [2d] SampleChareArray2d{...} //2d chare array
+
+       public class SampleObject{...}                                  //sample class
+
+       public chare SampleChare {
+           public entry SampleChare(){...}                             //constructor
+           public entry SampleChare(boolean flag){...} //constructor 2
+           public entry void test(SampleObject obj){...}       //entry method
+       }
+
+\end{verbatim}
+
+\subsection{Chare creation and method calls: }
+
+\begin{verbatim}
+       SampleChare@ sp = new SampleChare@();
+       SampleChareArray1d@ sp1 = new SampleChareArray1d@(x_dim);
+       SampleChareArray2d@ sp2 = new SampleChareArray2d@(x_dim, y_dim);
+       sp@test();
+       sp1@test();
+       sp1[index]@test();
+       sp2@test(int value);
+\end{verbatim}
+
+\subsection{Arrays:}
+
+\begin{verbatim}
+       Array<int> foo = new Array<int>([10]);  //1d array of integers of size 10
+       foo[i] = ...;
+       Array<double, 2> foo2 = new Array<double, 2>([s1, s2]); //2d array of size s1, s2
+       foo2[i, j] = ...;
+\end{verbatim}
+
+\subsection{SDAG statements:}
+These statements can be used inside of any entry method.
+
+\begin{verbatim}
+       when receiveMsg(SampleObject obj) {...}
+
+       overlap{        //two overlapping when statements
+               when receiveMsg1[i](int iter, SampleObject obj) {...}
+               when receiveMsg2[i](int iter, int value) {...}
+       }
+\end{verbatim}
+
+\subsection{Extern statements: }
+If you want to use any other C++ function/feature, you have to define it as {\it extern}.
+
+\begin{verbatim}
+       extern atoi;                    //define in the beginning of the file
+       int x = atoi(y);                //use anywhere
+\end{verbatim}
+
+\subsection{Reduction statements:}
+Currently only plain reductions are supported.
+
+\begin{verbatim}
+       contribute(CkCallback(CkReductionTarget(Main, done), mainProxy));
+\end{verbatim}
+
+\subsection{Some Charm++ statements that can be used in a Charj program:}
+
+\begin{verbatim}
+       CkExit();
+       CkPrintf();
+       CkMyPe();
+       CkNumPes();
+       CkMyNode();
+       CkNumNodes();
+       CkWallTimer();
+       thisProxy
+       thisIndex
+\end{verbatim}
+
+\end{document}