*** empty log message ***
authorTerry L. Wilmarth <wilmarth@uiuc.edu>
Mon, 28 Feb 2000 22:04:37 +0000 (22:04 +0000)
committerTerry L. Wilmarth <wilmarth@uiuc.edu>
Mon, 28 Feb 2000 22:04:37 +0000 (22:04 +0000)
26 files changed:
doc/charm++/Makefile [new file with mode: 0644]
doc/charm++/ack.tex [new file with mode: 0644]
doc/charm++/arrays.tex [new file with mode: 0644]
doc/charm++/chares.tex [new file with mode: 0644]
doc/charm++/comprundebug.tex [new file with mode: 0644]
doc/charm++/contacts.tex [new file with mode: 0644]
doc/charm++/further.tex [new file with mode: 0644]
doc/charm++/groups.tex [new file with mode: 0644]
doc/charm++/idl.tex [new file with mode: 0644]
doc/charm++/inhertmplt.tex [new file with mode: 0644]
doc/charm++/intro.tex [new file with mode: 0644]
doc/charm++/io.tex [new file with mode: 0644]
doc/charm++/keywords.tex [new file with mode: 0644]
doc/charm++/manual.tex [new file with mode: 0644]
doc/charm++/messages.tex [new file with mode: 0644]
doc/charm++/modules.tex [new file with mode: 0644]
doc/charm++/nodegroups.tex [new file with mode: 0644]
doc/charm++/othercalls.tex [new file with mode: 0644]
doc/charm++/overview.tex [new file with mode: 0644]
doc/charm++/quiesce.tex [new file with mode: 0644]
doc/charm++/readonly.tex [new file with mode: 0644]
doc/charm++/related.tex [new file with mode: 0644]
doc/charm++/sdag.tex [new file with mode: 0644]
doc/charm++/seqobjs.tex [new file with mode: 0644]
doc/charm++/syntaxchange.tex [new file with mode: 0644]
doc/charm++/tools.tex [new file with mode: 0644]

diff --git a/doc/charm++/Makefile b/doc/charm++/Makefile
new file mode 100644 (file)
index 0000000..2a8ddea
--- /dev/null
@@ -0,0 +1,33 @@
+TEXFILES= groups.tex related.tex ack.tex nodegroups.tex sdag.tex arrays.tex idl.tex seqobjs.tex inhertmplt.tex othercalls.tex intro.tex syntaxchange.tex chares.tex keywords.tex tools.tex contacts.tex manual.tex messages.tex quiesce.tex further.tex readonly.tex modules.tex overview.tex comprundebug.tex
+
+ps: $(TEXFILES)
+       touch index.tex
+       latex manual.tex
+       bibtex manual
+       makeindex -o index.tex manual.idx
+       latex manual.tex
+       latex manual.tex
+       dvips -o manual.ps manual.dvi
+
+html: $(TEXFILES)
+       latex manual.tex
+       latex2html manual.tex
+
+install:
+       rm -f /expand1/groupMosaic/distrib/newcharm++.manual.ps.gz
+       cp manual.ps /expand1/groupMosaic/distrib/newcharm++.manual.ps
+       gzip /expand1/groupMosaic/distrib/newcharm++.manual.ps
+       chmod 664 /expand1/groupMosaic/distrib/newcharm++.manual.ps.gz
+       rm -f /expand1/groupMosaic/html-manuals/newcharm++.manual/*
+       cp manual/* /expand1/groupMosaic/html-manuals/newcharm++.manual/
+       chmod 664 /expand1/groupMosaic/html-manuals/newcharm++.manual/*
+
+all: ps html install
+
+co:
+       co Makefile
+       co $(TEXFILES)
+
+clean: 
+       rm -f *.aux *.log *.dvi *.ps *.idx *.toc
+
diff --git a/doc/charm++/ack.tex b/doc/charm++/ack.tex
new file mode 100644 (file)
index 0000000..9fcf4ef
--- /dev/null
@@ -0,0 +1,44 @@
+\section*{Acknowlegements}
+
+\large
+The Charm software was developed as a group effort.  The earliest
+prototype, Chare Kernel(1.0), was developed by Wennie Shu and Kevin
+Nomura working with Laxmikant Kale.  The second prototype, Chare
+Kernel(2.0), a complete re-write with major design changes, was
+developed by a team consisting of Wayne Fenton, Balkrishna Ramkumar,
+Vikram Saletore, Amitabh B. Sinha and Laxmikant Kale. The translator
+for Chare Kernel(2.0) was written by Manish Gupta.  Charm(3.0), with
+significant design changes, was developed by a team consisting of
+Attila Gursoy, Balkrishna Ramkumar, Amitabh B.  Sinha and Laxmikant
+Kale, with a new translator written by Nimish Shah.  The Charm++
+implementation was done by Sanjeev Krishnan.  Charm(4.0) included
+Charm++ and was released in fall 1993.  Charm(4.5) was developed by
+Attila Gursoy, Sanjeev Krishnan, Milind Bhandarkar, Joshua Yelon,
+Narain Jagathesan and Laxmikant Kale.  Charm(4.8), developed by the
+same team included Converse, a parallel runtime system that allows
+interoperability among modules written using different paradigms
+within a single application. Charm++ runtime system was re-targetted
+at Converse. Syntactic extensions in Charm++ were dropped, and a
+simple interface translator was developed that, along with the Charm++
+runtime, became the Charm++ language.  The current version (5.0)
+includes a complete rewrite of the Charm++ runtime system (using C++)
+and the interface translator (done by Milind Bhandarkar).  It also
+includes several new features such as Chare Arrays (developed by
+Robert Brunner), and various libraries (written by Terry Wilmarth,
+Gengbin Zheng, Laxmikant Kale, Zehra Sura, Milind Bhandarkar, Robert
+Brunner, and Krishnan Varadarajan.) A coordination language
+``Structured Dagger'' has been implemented on top of Charm++ (Milind
+Bhandarkar), and included in this version.  IDL bindings for Charm++
+were developed by Jayant Desouza, Milind Bhandarkar and Gengbin
+Zheng. Several features have also been added to Converse. Dynamic
+seed-based load balancing has been implemented (Terry Wilmarth and
+Joshua Yelon), a client-server interface for Converse programs, and
+debugging support has been added (Parthasarathy Ramachandran, Jeff
+Wright, and Milind Bhandarkar).  Converse has been ported to new
+platforms including ASCI Red (Joshua Yelon), Cray T3E (Robert
+Brunner), and SGI Origin2000 (Milind Bhandarkar).  The test suite for
+Charm++ was developed by Michael Lang, Jackie Wang, and Fang
+Hu. Projections, the performance visualization and analysis tool, was
+redesigned and rewritten using Java by Michael Denardo.
+
+\normalsize
diff --git a/doc/charm++/arrays.tex b/doc/charm++/arrays.tex
new file mode 100644 (file)
index 0000000..980f611
--- /dev/null
@@ -0,0 +1,99 @@
+\subsection{Chare Arrays}
+
+Chare arrays \index{arrays} are arbitrarily-sized collections of chares,
+referenced by a globally unique array identifier of type \keyword{CkArrayID}
+\index{CkArrayID} and an index. 
+
+\uw{ArrayType} is specified in the interface file as:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{array} \uw{ArrayType} \{ \\
+\> \> \kw{entry} \uw{ArrayType}(\uw{MessageType1} *); \\
+\> \> \kw{entry void} \uw{EntryPointName2}(\uw{MessageType2} *); \\
+\> \};
+\end{tabbing}
+
+The definition has the form:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{class} \uw{ArrayType} : \kw{public ArrayElement} [: superclass
+names] \{ \\
+\> \> // Data and member functions as in C++ \\
+\> \> // One or more {\it entry method} \index{entry method}
+definitions of the form \\
+\> \kw{public}: \\
+\> \> \uw{ArrayType}(\uw{MessageType1} *{\it MsgPointer}) \\
+\> \> \> \{ // C++ code block  \} \\
+\> \> \kw{void} \uw{EntryPointName2}(\uw{MessageType2} *{\it MsgPointer}) \\
+\> \> \> \{ // C++ code block  \} \\
+\> \};
+\end{tabbing}
+
+In most respects, array elements are identical to chares.  Differences
+include variations in the creation and remote invocation syntax, to
+include the array size and array index.  Also, the messages handled by
+array elements must be subclasses of the \keyword{ArrayMessage}
+\index{ArrayMessage} type.
+
+
+\subsubsection{Chare Array Creation}
+
+Given the following code for a \index{array}\index{chare array}chare array declaration:
+In the ``.ci'' file:
+
+\begin{verbatim}
+array G {
+  entry G(M1 *);
+  entry void someEntry(M2 *);
+};
+\end{verbatim}
+
+and in the ``.h'' file:
+
+\begin{verbatim}
+class G : public ArrayElement {
+  public:
+    G(M1 *);
+    void someEntry(M2 *);
+
+    // Optional, for migratable elements
+    G(ArrayElementMigrateMsg *);
+    void packsize();
+    void pack();
+};
+\end{verbatim}
+
+An \index{array}array can be created as follows:
+
+\begin{verbatim}
+CProxy_A *pA = new CProxy_A(num_elements);
+   // or
+CkArrayID aid = CProxy_G::ckNew(num_elements);
+CProxy_G g(aid);
+\end{verbatim}
+
+
+\subsubsection{Method Invocation on Chare Arrays}
+
+To invoke an entry method f on a chare array, you need to have a proxy
+for it.  If you have a global array id (of type CkArrayID) for the
+array, you can construct the proxy as follows:
+
+\begin{verbatim}
+CkArrayID aid = CProxy_G::ckNew(num_elements);
+// aid may be passed in messages to other objects
+CProxy_G g(aid);
+
+// Chare array message invocation
+g[i].f(msg);
+
+// Chare array broadcast
+g.f(msg);
+\end{verbatim}
+
+
+
+
+
diff --git a/doc/charm++/chares.tex b/doc/charm++/chares.tex
new file mode 100644 (file)
index 0000000..fbeda84
--- /dev/null
@@ -0,0 +1,228 @@
+\subsection{Chare Objects}
+
+\index{chare}Chares are concurrent objects with methods that can be invoked
+remotely.  These methods are known as \index{entry method}entry methods, and 
+must be specified in the interface ({\tt .ci}) file:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{chare} \uw{ChareType} \{ \\
+\> \> \kw{entry} \uw{ChareType}(\uw{MessageType1} *); \\
+\> \> \kw{entry void} \uw{EntryMethodName2}(\uw{MessageType2} *); \\
+\> \};
+\end{tabbing}
+
+A corresponding \index{chare}chare definition in the {\tt .h} file would 
+have the form:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{class} \uw{ChareType} : \kw{public Chare} [: superclass names] \{ \\
+\> \>   // Data and member functions as in C++ \\
+\> \>   // One or more {\it entry method} \index{entry method}
+definitions of the form: \\
+\> \kw{public}: \\
+\> \> \uw{ChareType}(\uw{MessageType1} *{\it MsgPointer}) \\
+\> \> \> \{ // C++ code block  \} \\
+\> \> \kw{void} \uw{EntryMethodName2}(\uw{MessageType2} *{\it MsgPointer}) \\
+\> \> \> \{ // C++ code block  \} \\
+\> \};
+\end{tabbing}
+
+\index{chare}
+Chares are concurrent objects encapsulating medium-grained units of
+work.  Chares can be dynamically created on any processor; there may
+be thousands of chares on a processor. The location of a chare is
+usually determined by the dynamic load balancing strategy; however,
+once a chare commences execution on a processor, it does not migrate
+to other processors\footnote{Except when it is part of an array.}.  
+Chares do not have a default ``thread of
+control'': the entry methods \index{entry methods} in a
+chare execute in a message driven fashion upon the arrival of a 
+message\footnote{Threaded methods augment this behavior since they execute in
+a separate user-level thread, and thus can block to wait for data.}.
+
+The entry method definition specifies a function that is executed {\it
+without interruption} when a message is received and scheduled for
+processing. Only one message per chare is processed at a time.  Entry
+methods are defined exactly as normal C++ function members, except
+that they must have the return value \kw{void} (except for the
+constructor entry method which may not have a return value, and for a {\em synchronous}
+entry method, which is invoked by a {\em threaded} method in a remote chare) and they
+must have exactly one argument which is a pointer to a
+message.
+
+Each chare instance is identified by a {\it handle} \index{handle}
+which is essentially a global pointer, and is unique across all
+processors.  The handle of a chare has type \index{CkChareID}
+\keyword{CkChareID}.  The
+variable \kw{thishandle} \index{thishandle} holds the handle of the
+chare whose entry function or public function is currently executing.
+\kw{thishandle} is a public instance variable of the chare object
+(it is inherited from the system-defined superclass for chares, \kw{Chare}).
+\kw{thishandle} can be used to set fields in a message. This  
+mechanism allows chares to send their handles to other chares.
+
+\subsubsection{Chare Creation}
+\label{chare creation}
+
+First, a \index{chare}chare needs to be declared, both in {\tt .ci} file and in
+{\tt .h} file, as stated in Section 2.3.3. The following is an example of
+declaration for a \index{chare}chare of user-defined type \uw{C}, where \uw{M1}
+and \uw{M2} are user-defined \index{message}message types, and \uw{someEntry}
+is an entry method.
+
+In the {\tt mod.ci} file we have:
+
+\begin{verbatim}
+module mod {
+  chare C {
+    entry C(M1 *);
+    entry void someEntry(M2 *);
+  };
+}
+\end{verbatim}
+
+and in the {\tt mod.h} file:
+
+\begin{verbatim}
+#include "mod.decl.h"
+class C : public Chare {
+  public:
+    C(M1 *);
+    void someEntry(M2 *);
+};
+\end{verbatim}
+
+Now one can use the class \kw{CProxy}\_\uw{chareType}\index{CProxy\_} to create
+a new instance of a \index{chare}chare.  Here \uw{chareType} gets replaced with
+whatever \index{chare}chare type we want.  For the above example, proxies would
+be of type \kw{CProxy}\_\uw{C}. A number of \index{chare}chare creation calls
+exist as static or instance methods of class \kw{CProxy}\_\uw{chareType}:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{CProxy}\_\uw{chareType}::\kw{ckNew}(\uw{MessageType} *{\it
+msgPtr}, \kw{CkChareID} *{\it vHdl}, \kw{int} {\it destPE});
+\end{tabbing}
+
+where each parameter above is optional and where
+
+\begin{itemize}
+
+\item \uw{chareType} is the name of the type of \index{chare}chare to be
+created.
+
+\item {\it msgPtr} is a pointer to a \index{message}message whose type must
+correspond to the parameter for the \index{constructor}constructor entry method
+\uw{chareType}(\uw{MessageType} *) in \index{chare}chare \uw{chareType}.  This
+parameter may be omitted if the \index{constructor}constructor takes a void
+parameter.
+
+\item {\it vHdl} is a pointer to a \index{chare}chare handle of type
+\kw{CkChareID}, which is filled by the \kw{ckNew} method. This optional
+argument can be used if the user desires to have a {\em virtual} handle
+\index{virtual handle} to the instance of the \index{chare}chare that will be
+created. This handle is useful for sending \index{message}messages to the
+\index{chare}chare, even though it has not yet been created on any processor.
+Messages sent to this virtual handle are either queued up to be sent to the
+\index{chare}chare after it has been created, or simply redirected if the
+\index{chare}chare has already been created. For performance reasons,
+therefore, virtual handles should be used only when absolutely necessary.
+Virtual handles are otherwise like normal \index{handle}handles, and may be
+sent to other processors in \index{message}messages.  
+
+\item {\it destPE}: when a \index{chare}chare is to be created at a specific
+processor, the {\it destPE} is used to specify that processor.  Note that, in
+general, for good \index{load balancing}load balancing, the user should let
+\charmpp\ determine the processor on which to create a \index{chare}chare.
+Under unusual circumstances, however, the user may want to choose the
+destination processor.  If a process replicated on every processor is desired,
+then a \index{chare group}chare group should be used.  If no particular
+processor is required, the parameter can be omitted, or
+\index{CK\_PE\_ANY}\kw{CK\_PE\_ANY}.
+
+\end{itemize}
+
+The \index{chare}chare creation method deposits the \index{seed}{\em seed} for
+a chare in a pool of seeds and returns immediately. The \index{chare}chare will
+be created later on some processor, as determined by the dynamic \index{load
+balancing}load balancing strategy. When a \index{chare}chare is created, it is
+initialized by calling its   \index{constructor}constructor \index{entry
+method}entry method with the \index{message}message parameter specified to the
+\index{chare}chare creation method.  The method operator does not return any
+value but fills in the \index{virtual handle}virtual handle to the newly
+created \index{chare}chare if specified.
+
+The following are some examples on how to use the \index{chare}chare creation
+method to create chares.
+
+\begin{enumerate}
+\item{This will create a new \index{chare}chare of type \uw{C} on {\it any} processor:}
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \uw{MessageType} *{\it MsgPtr} = \kw{new} \uw{MessageType}; \\
+\> \kw{CProxy}\_\uw{C} *{\it pC} = \kw{new} \kw{CProxy}\_\uw{C}({\it
+MsgPtr}); \\
+\> \> // or \\
+\> \uw{MessageType} *{\it MsgPtr} = \kw{new} \uw{MessageType}; \\
+\> \kw{CProxy}\_\uw{C}::\kw{ckNew}({\it MsgPtr});
+\end{tabbing} 
+
+\item{This will create a new \index{chare}chare of type \uw{C} on processor {\it destPE}:}
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \uw{MessageType} *{\it MsgPtr} = \kw{new} \uw{MessageType}; \\
+\> \kw{CProxy}\_\uw{C}::\kw{ckNew}({\it MsgPtr}, {\it destPE});
+\end{tabbing}
+
+\item{The following first creates a \kw{CkChareID} {\it cid},
+then creates a new \index{chare}chare of type \uw{C} on processor {\it destPE}:}
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \uw{MessageType} *{\it MsgPtr} = \kw{new} \uw{MessageType}; \\
+\> \kw{CkChareID} {\it cid}; \\
+\> \kw{CProxy}\_\uw{C}::\kw{ckNew}({\it MsgPtr}, \&{\it cid}, {\it
+destPE}); \\
+\> \kw{CProxy}\_\uw{C} {\it c}({\it cid});
+\end{tabbing}
+
+\end{enumerate}
+
+\subsubsection{Method Invocation on Chares}
+
+Before sending a \index{message}message to a \index{chare}chare via an
+\index{entry method}entry method, we need to get a \index{proxy}{\it proxy} of
+that \index{chare}chare using either the chare identifier, or by creating the
+proxy directly from the \index{chare}chare creation (see Section~\ref{chare
+creation}. The following code creates a proxy from a
+\index{CkChareID}\kw{CkChareID}.
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> \kw{CProxy}\_\uw{chareType} {\it chareProxy}({\it chareID});
+\end{tabbing}
+
+This declares a proxy named {\it chareProxy} of \uw{chareType} using {\it
+chareID}.  Alternatively, we can create a proxy pointer:
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> \kw{CProxy}\_\uw{chareType} *{\it chareProxyPointer} = \kw{new
+CProxy}\_\uw{chareType}({\it chareHandle}); \end{tabbing}
+
+This creates a pointer named {\it chareProxyPointer} which points to the proxy. 
+
+A message \index{message} may be sent to a \index{chare}chare using the
+notation:
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> {\it chareProxy}$.$\uw{EntryMethod}({\it MessagePointer}) \\ \>
+\> or, \\ \> {\it chareProxyPointer}$->$\uw{EntryMethod}({\it MessagePointer})
+\end{tabbing}
+
+This sends the message pointed to by {\it MessagePointer} to the
+\index{chare}chare whose proxy/proxy pointer is {\it chareProxy}/{\it
+chareProxyPointer} at the \index{entry method}entry method \uw{EntryMethod},
+which must be a valid entry method of that \index{chare}chare type. This call
+is asynchronous and non-blocking; it returns immediately after sending the
+message. 
diff --git a/doc/charm++/comprundebug.tex b/doc/charm++/comprundebug.tex
new file mode 100644 (file)
index 0000000..4cad884
--- /dev/null
@@ -0,0 +1 @@
+\section{Compiling, Running and Debugging Charm++/Converse Programs}
diff --git a/doc/charm++/contacts.tex b/doc/charm++/contacts.tex
new file mode 100644 (file)
index 0000000..d050fb1
--- /dev/null
@@ -0,0 +1,35 @@
+\subsection{Contacts}
+\label{Distribution}
+
+While we can promise neither bug-free software nor immediate solutions   
+to all problems, \charmpp\ is a stable system and it is our intention to
+keep it as up-to-date and usable as our resources will allow
+by responding quickly to questions and bug reports.  To that
+end, there are mechanisms in place for contacting Charm users
+and developers. 
+
+Our software is made available for research use and evaluation.
+For the latest software distribution, further information about {\sc
+Charm}/\charmpp\ and information on how to contact the Parallel
+Programming laboratory, see our website at {\it
+http://charm.cs.uiuc.edu/}.  The software is also available by
+anonymous ftp, from a.cs.uiuc.edu, under the directory
+pub/research-groups/CHARM.  
+
+If retrieval of a publication via these channels is not possible,
+please send electronic mail to {\tt kale@cs.uiuc.edu} or postal mail to:
+
+{\bf 
+\begin{tabbing}
+\hspace{0.5in}\=\hspace{0.3in}\=\hspace{0.3in}\=\hspace{0.3in}\= \kill
+\> Laxmikant Kale \\
+\> Department of Computer Science \\
+\> University of Illinois \\
+\> 1304 West Springfield Avenue \\
+\> Urbana, IL 61801 \\
+\end{tabbing}
+}
+
+A mailing list exists for announcements about software releases and
+updates relating to \charmpp/{\sc Converse}.  To subscribe, send
+e-mail to: ???????.
diff --git a/doc/charm++/further.tex b/doc/charm++/further.tex
new file mode 100644 (file)
index 0000000..7034bb4
--- /dev/null
@@ -0,0 +1,2 @@
+\section{Further Information}
+
diff --git a/doc/charm++/groups.tex b/doc/charm++/groups.tex
new file mode 100644 (file)
index 0000000..2d514eb
--- /dev/null
@@ -0,0 +1,186 @@
+\subsection{Group Objects}
+
+A {\sl group\footnote{Originally called {\em Branch Office Chare} or 
+{\em Branched Chare}}} \index{group}is a collection of chares where 
+there exists \index{chare}one chare (or {\sl branch}) on each
+processor.   Each branch has its own data members.  Groups have
+a definition syntax similar to normal chares, except that they must
+inherit from the system defined class \keyword{Group}, rather than
+\keyword{Chare}.
+
+In the interface file, we declare
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{group} \uw{GroupType} \{ \\
+\> \>  // Interface specifications as for normal chares \\
+\> \};
+\end{tabbing}
+
+In the {\tt .h} file, we define \uw{GroupType} as follows:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{class} \uw{GroupType} : \kw{public Group} [,other superclasses
+] \{ \\
+\> \> // Data and member functions as in C++ \\
+\> \> // Entry functions as for normal chares \\
+\> \};
+\end{tabbing}
+
+A group is identified by a globally unique group identifier, whose type is
+\kw{CkGroupID}. \index{CkGroupID}This identifier is common to all of the 
+group's branches and can be obtained from the variable \keyword{thisgroup},
+\index{thisgroup}which is a public local variable of the \keyword{Group} 
+superclass.  For groups, \kw{thishandle} \index{thishandle} is the handle of 
+the particular branch in which the function is executing: it is 
+a normal chare handle.
+
+Groups can be used to implement data-parallel operations easily.
+In addition to sending messages to a particular branch of a group, one can 
+broadcast messages to all branches of a group.
+See Section~\ref{sending messages}.
+
+There can be many instances corresponding to a group type.  Each
+instance has a different group handle, and its own set of branches.
+
+\subsubsection{Group Creation}
+
+\noindent {\bf Chare Group Declaration}:
+
+\noindent Given a {\tt .ci} file as follows:
+
+\begin{verbatim}
+group G {
+  entry G(M1 *);
+  entry void someEntry(M2 *);
+};
+\end{verbatim}
+
+\noindent and the following {\tt .h} file:
+
+\begin{verbatim}
+class G : public Group {
+  public:
+    G(M1 *);
+    void someEntry(M2 *);
+};
+\end{verbatim}
+
+we can create a \index{group}group in a manner similar to a regular \index{chare}chare.  Note
+the difference in how the \index{virtual handle}virtual handle is created.
+
+\begin{verbatim}
+M1 *m1 = new M1;
+CProxy_G *pG = new CProxy_G(m1);
+  // or
+CkGroupID gid = CProxy_G::ckNew(m1);
+CProxy_G g(gid);
+\end{verbatim}
+
+\subsubsection{Method Invocation on Groups}
+
+Similarly, before sending a message to a \index{group}group via an entry
+method, we need to get a proxy of that group using the group identifier (a
+\index{CkGroupID}\kw{CkGroupID}). The syntax for obtaining the proxy or a proxy
+pointer is:
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> \kw{CProxy}\_\uw{groupType} {\it groupProxy}({\it groupID}); \\
+\> \> or, \\ \> \kw{CProxy}\_\uw{groupType} *{\it groupProxyPointer} = \kw{new
+CProxy}\_\kw{groupType}({\it groupID}); \end{tabbing}
+
+The first approach creates a proxy to the group represented by {\it groupID}
+while the second creates a pointer named {\it groupProxyPointer} to a proxy to
+the group represented by {\it groupID}. 
+
+A message may be sent to a particular \index{branch}branch of group using the
+notation:
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> {\it groupProxy}$.$\uw{EntryMethod}({\it MessagePointer}, {\it
+Processor}) \\ \> \> or, \\ \> {\it groupProxyPointer}$->$\uw{EntryMethod}({\it
+MessagePointer}, {\it Processor}) \end{tabbing}
+
+This sends the message in {\it MessagePointer} to the \index{branch}branch of
+the group represented by {\it groupID} which is on processor number {\it
+Processor} at the entry method \uw{EntryMethod}, which must be a valid entry
+method of that group type. This call is asynchronous and non-blocking; it
+returns immediately after sending the message.
+
+A message may be broadcast \index{broadcast} to all branches of a branched
+chare (i.e., to all processors) using the notation :
+
+\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
+\=~~~~ \kill \> {\it groupProxy}$.$\uw{EntryMethod}({\it MessagePointer}) \\ \>
+{\it groupProxyPointer}$->$\uw{EntryMethod}({\it MessagePointer}) \end{tabbing}
+
+This sends the message in {\it MessagePointer} to all branches of the group at
+the entry method {\sf EntryMethod}, which must be a valid entry method of that
+group type. This call is asynchronous and non-blocking; it returns immediately
+after sending the message.
+
+Note that the programmer relinquishes control of a message after sending it.
+Further access to the message field can cause runtime errors.
+
+Similarly, methods could be invoked either on a particular \index{branch}branch
+of a \index{nodegroup}nodegroup by specifying a {\em node number} as a method
+parameter. In the absence of such a parameter, the call is treated as broadcast
+on a \index{nodegroup}nodegroup, i.e. executed by all nodes. When a method is
+invoked on a particular \index{branch}branch of a \index{nodegroup}nodegroup,
+it may be executed by {\em ANY} processor in that node. Thus two invocations of
+a specific method on a particular \index{branch}branch of a
+\index{nodegroup}nodegroup may be carried out {\em simultaneously} by two
+different processors of the node. If that method contains code that
+should be executed by only one processor at a time, the method should
+be flagged
+\index{exclusive}\kw{exclusive} in the interface file. If a method \uw{M} of a
+nodegroup \uw{NG} is marked exclusive, it means that while that method is being
+executed by any processor within a node, no other processor within the same
+node may execute any other {\em exclusive} method of that
+\index{nodegroup}nodegroup \index{branch}branch.  Other processors are free to
+execute other {\em non-exclusive} methods of that nodegroup
+\index{branch}branch, however.
+
+Sequential objects, chares and other groups can access public members of the
+\index{branch}branch of a group \index{group} {\it on their processor} using
+the following notation:
+
+((\uw{GroupType}*)\kw{CkLocalBranch}(\kw{CkGroupID} {\it groupID}))-$>${\it
+DataMember}, and \\ ((\uw{GroupType}*)\kw{CkLocalBranch}(\kw{CkGroupID} {\it
+groupID}))-$>$\uw{method}().  \index{CkLocalBranch}
+
+Thus a dynamically created \index{chare}chare can call a public method of a
+group without needing to know which processor it actually resides: the method
+executes in the local \index{branch}branch of the group. 
+
+Similarly, the local \index{branch}branch of a \index{nodegroup}\kw{nodegroup}
+can be accessed using \index{CkLocalNodeBranch}\kw{CkLocalNodeBranch()}
+function. Thus data members could be accessed/modified or methods could be
+invoked on a \index{branch}branch of a \kw{nodegroup} using this function. Note
+that such accesses are {\em not} thread-safe by default. Concurrent invocation
+of a method on a \index{nodegroup}nodegroup by different processors within a
+node may result in unpredictable runtime behavior.  One way to avoid this is to
+use node-level locks (described in Converse manual.)
+
+Both \index{CkLocalBranch}\kw{CkLocalBranch} and \index{CkLocalNodeBranch}
+\kw{CkLocalNodeBranch} return generic ({\tt void *}) pointers. They need to be
+cast to pointers of appropriate classes before invoking methods or accesing
+data members. \charmpp\ provides another way to do this using the generated
+\index{proxy}{\em proxy} classes. One may call the static method
+\kw{ckLocalBranch} or \kw{ckLocalNodeBranch} of the proxy class of appropriate
+group or \index{nodegroup}nodegroup to get the correct type of pointer.  For
+example, method \uw{foo} can to be invoked on the local \index{branch}branch of
+a group \uw{G} with \uw{gid} as CkGroupID as:
+
+(\kw{CProxy}\_\uw{G}::\kw{ckLocalBranch}({\it gid}))-$>$\uw{foo}(...);\\
+\index{ckLocalBranch}
+
+
+
+
+
+
+
+
+
diff --git a/doc/charm++/idl.tex b/doc/charm++/idl.tex
new file mode 100644 (file)
index 0000000..9c8c22a
--- /dev/null
@@ -0,0 +1,82 @@
+\section{Interface Description Language (IDL)}
+
+The Interface Description Language(IDL) is the language used to
+describe the interfaces that client objects call and server object
+implementations provide.
+
+A typical simple IDL interface file follows:
+
+\begin{verbatim}
+module myModule {
+  interface myClass1 {
+    attribute long myAttr1;
+    attribute int myAttr2;
+    oneway void myMethod1(
+        in char c,
+        in short s,
+        in long l,
+        in unsigned short us,
+        in unsigned long ul,
+        out float f,
+        inout double d,
+       out int a[10]);
+  };
+};
+\end{verbatim}
+
+An interface can have attributes as well as operations.  Array
+parameters in operation declaration are supported. Templates and String
+types are currently not supported.
+
+\noindent {\bf Parameter declaration}:
+
+Parameter declaration attributes include:
+\begin{itemize}
+\item {\bf in} - the parameter is passed from client to server
+\item {\bf out} - the parameter is passed from server to client
+\item {\bf inout} - the parameter is passed in both directions
+\end{itemize}
+
+\noindent {\bf How to write client/server side code }:
+
+To define the classes declared in the {\tt .idl} file, one must write
+{\tt .h} and {\tt .C} file for the classes as usual. For example, in the
+{\tt .idl} file, we have:
+
+\begin{verbatim}
+module myModule {
+  interface myClass1 {
+    oneway void myMethod1( in char c);
+  };
+};
+\end{verbatim}
+
+In the  {\tt .h} file:
+
+\begin{verbatim}
+class myClass1 {
+  public:
+    void myMethod1( char );
+    myClass1();
+    ~myClass1();
+};
+\end{verbatim}
+
+We implement these methods in the {\tt .C} file.
+
+Instead of using {\tt myClass1} directly, one should declare and use the
+class by using the name {\tt CImyClass1}. For example, in {\tt main.C}: 
+
+\begin{verbatim}
+main::main(CkArgMsg* m)
+{
+  CImyClass1 a;
+  // create the object
+  a.ciSetProc(CI_PE_ANY).ciCreate();
+  // call method
+  a.myMethod1('a');
+  // delete the object
+  a.ciDelete();
+}
+\end{verbatim}
+
diff --git a/doc/charm++/inhertmplt.tex b/doc/charm++/inhertmplt.tex
new file mode 100644 (file)
index 0000000..2eb4e34
--- /dev/null
@@ -0,0 +1,202 @@
+\section{Inheritance and Templates in Charm++}
+\label{inheritance and templates}
+
+\charmpp\ 5.0 supports inheritance among \charmpp\ objects such as
+chares, groups, and messages. This, along with facilities for generic
+programming using \CC\ style templates for \charmpp\ objects, is a
+major enhancement over the previous version of \charmpp.
+
+\subsection{Chare Inheritance}
+\index{inheritance}
+Chare inheritance makes it possible to remotely invoke methods of a base
+chare \index{base chare} from a proxy of a derived
+chare.\index{derived chare} Suppose a base chare is of type 
+\uw{BaseChare}, then the derived chare of type \uw{DerivedChare} needs to be
+declared in the \charmpp\ interface file to be explicitly derived from
+\uw{BaseChare}. Thus, the constructs in the {\tt .ci} file should look like:
+
+\begin{verbatim}
+  chare BaseChare {
+    BaseChare(someMessage *);
+    baseMethod(void);
+    ...
+  }
+  chare DerivedChare : BaseChare {
+    DerivedChare(otherMessage *);
+    derivedMethod(void);
+    ...
+  }
+\end{verbatim}
+
+Note that the access specifier \kw{public} is omitted, because \charmpp\
+interface translator only needs to know about the public inheritance,
+and thus \kw{public} is implicit. A Chare can inherit privately from other
+classes too, but the \charmpp\ interface translator does not need to know
+about it, because it generates support classes ({\em proxies}) to remotely
+invoke only \kw{public} methods.
+
+The class definitions of both these chares should look like:
+
+\begin{verbatim}
+  class BaseChare : public Chare {
+    // private or protected data
+    public:
+      BaseChare(someMessage *);
+      baseMethod(void);
+  };
+  class DerivedChare : public BaseChare {
+    // private or protected data
+    public:
+      DerivedChare(otherMessage *);
+      derivedMethod(void);
+  };
+\end{verbatim}
+
+Now, it is possible to create a derived chare, and invoke methods of base
+chare from it, or to assign a derived chare proxy to a base chare proxy
+as shown below:
+
+\begin{verbatim}
+  ...
+  otherMessage *msg = new otherMessage();
+  CProxy_DerivedChare *pd = new CProxy_DerivedChare(msg);
+  pd->baseMethod();     // OK
+  pd->derivedMethod();  // OK
+  ...
+  Cproxy_BaseChare *pb = pd;
+  pb->baseMethod();    // OK
+  pb->derivedMethod(); // ERROR
+\end{verbatim}
+
+
+Note that \CC\ calls the default constructor \index{default
+constructor} of the base class from any
+constructor for the derived class where base class constructor is not
+called explicitly. Therefore, one should always provide a default constructor
+for the base class to avoid explicitly calling another base class constructor.
+
+Multiple inheritance \index{multiple inheritance} is also allowed for
+Chares and Groups. However, one should make sure that each of the base
+classes inherit ``virtually'' from \kw{Chare} or \kw{Group}, so that a
+single copy of \kw{Chare} or \kw{Group} exists for each multiply
+derived class.
+
+One may have {\em virtual} entry methods \index{virtual} in base chare
+classes. They are specified by the entry attribute \kw{virtual} in the
+interface file. Also, such a method could be pure virtual \index{pure
+virtual} (where implementation of this method is not given.) It is
+noted with the usual \CC\ syntax of ``{\tt =0}'' even in the interface
+file. Base classes with pure virtual methods are called {\em abstract}
+base classes \index{abstract base class} in OO-lingo. Note that,
+though instances of abstract base chares cannot be created, a proxy
+objects of such a type can be created by constructing it with the
+chareID of the concrete derived chare. Invoking methods on this proxy
+object would invoke those methods remotely on the concrete derived
+class instance.
+
+\subsection{Inheritance for Messages}
+\index{message inheritance}
+
+Similar to Chares, messages can also be derived from base messages. One needs
+to specify this in the \charmpp\ interface file similar to the Chare
+inheritance specification (that is, without the \kw{public} access specifier.)
+Message inheritance makes it possible to send a message of derived type to
+the method expecting a base class message.
+
+\subsection{Generic Programming Using Templates}
+\index{templates}
+
+One can write ``templated'' code for Chares, Groups, Messages and other 
+\charmpp\  entities using familiar \CC\ template syntax (almost). The
+\charmpp\ interface translator now recognizes most of the \CC\
+templates syntax, including a variety of formal parameters, default
+parameters, etc. However, not all \CC\ compilers currently recognize
+templates in ANSI drafts, therefore the code generated by \charmpp\
+for templates may not be acceptable to some current \CC\
+compilers\footnote{
+Most modern \CC\ compilers belong to one of the two camps. One that 
+supports Borland style template instantiation, and the other that
+supports AT\&T Cfront style template instantiation. In the first,
+code is generated for the source file where the instantiation is seen.
+GNU \CC\ falls in this category.
+In the second, which template is to be instantiated, and
+where the templated code is seen is noted in a separate area 
+(typically a local directory), and then just before linking all the
+template instantiations are generated. Solaris CC 5.0 belongs to this
+category. For templates to work for compilers in the first category
+such as for GNU \CC\ all the templated code needs to be visible to the
+compiler at the point of instantiation, that is, while compiling the 
+source file containing the template instantiation. For a variety of
+reasons, \charmpp\ interface translator cannot generate all the templated
+code in the declarations file {\tt *.decl.h}, which is included in the
+source file where templates are instantiated. Thus, for \charmpp\ generated
+templates to work for GNU \CC\ even the definitions file {\tt *.def.h}
+should be included in the \CC\ source file. However, this file may
+contain other definitions apart from templates that will be duplicated if
+the same file is included in more than one source files. To alleviate 
+this problem, we have to do a little trick. Fortunately, this trick works for
+compilers supporting both Borland-style and Cfront-style template 
+instantiation, therefore, code using this trick will be portable. The trick
+is to include {\tt *.def.h} with a preprocessor symbol 
+\kw{CK\_TEMPLATES\_ONLY} defined, whenever templates defined in an
+\kw{extern} module are instantiated. If your
+interface file does not contain template declarations or definitions,
+you need not bother about including {\tt *.def.h} for \kw{extern} modules.
+For example, if module {\tt stlib} contains template definitions, 
+that you may want to instantiate in another module called {\tt pgm},
+then {\tt pgm.C} should include {\tt stlib.def.h} 
+with \kw{CK\_TEMPLATES\_ONLY} defined. Of course, {\tt stlib.decl.h} needs
+to be included at the top of {\tt pgm.C}. 
+}. 
+
+The \charmpp\ interface file should contain the template
+definitions as well as the instantiation. For example, if a message
+class \uw{TMessage} is templated with a formal type parameter 
+\uw{DType}, then every instantiation of \uw{TMessage} should be specified
+in the \charmpp\ interface file. An example will illustrate this better:
+\index{template}
+
+\begin{verbatim}
+  template <class DType=int, int N=3> message TMessage;
+  message TMessage<>; // same as TMessage<int,3>
+  message TMessage<double>; // same as TMessage<double, 3>
+  message TMessage<UserType, 1>;
+\end{verbatim}
+
+Note the use of default template parameters. It is not necessary for
+template definitions and template instantiations to be part of the
+same module.  Thus, templates could be defined in one module, and
+could be instantiated in another module \index{module}, as long as the
+module defining a template is imported into the other module using the
+\kw{extern module} construct. Thus it is possible to build a standard
+\charmpp\ template library. Here we give a flavor of possibilities:
+
+\begin{verbatim}
+module SCTL {
+  template <class dtype> message  Singleton;
+  template <class dtype> group Reducer {
+    entry Reducer(void);
+    entry void submit(Singleton<dtype> *);
+  }
+  template <class dtype> chare ReductionClient {
+    entry void recvResult(Singleton<dtype> *);
+  }
+};
+
+module User {
+  extern module SCTL;
+  message Singleton<int>;
+  group Reducer<int>;
+  chare RedcutionClient<int>;
+  chare UserClient : ReductionClient<int> {
+    entry UserClient(void);
+  }
+};
+\end{verbatim}
+
+The \uw{Singleton} message is a template for storing one element of
+any \uw{dtype}. The \uw{Reducer} is a group template for a
+spanning-tree reduction, which is started by submitting data to the
+local branch. It also contains a public method to register the
+\uw{ReductionClient} (or any of its derived types), which acts as a
+callback to receive results of a reduction.
diff --git a/doc/charm++/intro.tex b/doc/charm++/intro.tex
new file mode 100644 (file)
index 0000000..b5cadde
--- /dev/null
@@ -0,0 +1,165 @@
+\section{Introduction}
+
+%update as you wish
+
+This manual describes \charmpp, an object oriented portable parallel
+programming language based on C++. Its program structure, execution
+model, interface language constructs and runtime system calls are
+described here\footnote{For a description of the underlying design
+philosophy please refer to the following papers :\\
+    L. V. Kale and Sanjeev Krishnan,
+    {\em ``CHARM++ : Parallel Programming with Message-Driven Objects''},
+    in ``Parallel Programming Using C++'',
+    MIT Press, 1995. \\
+    L. V. Kale and Sanjeev Krishnan,
+    {\em ``CHARM++ : A Portable Concurrent Object Oriented System
+    Based On C++''},
+    Proceedings of the Conference on Object Oriented Programming,
+    Systems, Languages and Applications (OOPSLA), September 1993.
+}.
+% Change to citations in appendices. 
+
+\charmpp\ has continuously evolved since the OOPSLA 1993 paper.
+The current version does not augment the C++ syntax, and does not
+use a \charmpp\ translator as in previous versions. Instead, efforts
+are made to convert most of the older constructs to calls into the
+runtime library, with minimal language constructs used to describe
+the interfaces.
+
+\charmpp\ is an explicitly parallel language based on C++ with a
+runtime library for supporting parallel computation. 
+It provides a clear separation between sequential
+and parallel objects.  The execution model of \charmpp\ is message
+driven, thus helping one write programs that are latency-tolerant.
+\charmpp\ supports dynamic load balancing while creating new work as well
+as periodically, based on object migration. 
+Several dynamic load balancing strategies are
+provided.  \charmpp\ supports both irregular as well as regular,
+data-parallel applications.
+It is based on the {\sc Converse} interoperable runtime system for
+parallel programming.
+
+Currently the parallel platforms supported by \charmpp\ are the 
+IBM SP, SGI Origin2000, Cray T3E, Intel Paragon,
+a single workstation or a network of workstations
+from Sun Microsystems (Solaris), IBM RS-6000 (AIX)
+SGI (IRIX 5.3 or 6.4), HP (HP-UX), and Intel x86 (Linux, Windows NT).
+\charmpp\ programs can run without changing the source on all these platforms.
+Please see the {\sl Charm++/Converse Installation and Usage Manual}
+for details about installing, compiling and running \charmpp\
+programs.
+
+For a description of the C-based {\sc Charm} parallel programming system,
+please refer to the {\sl Charm Programming Language Manual} and the
+{\sl Tutorial Introduction to Charm}\footnote{{\sc Charm} is no longer
+actively supported and maintained, and these manuals are kept only for
+offering the historical perspectives.}.
+
+\subsection{Overview}
+
+%update as you wish
+
+\charmpp\ is an object oriented parallel language. What sets \charmpp\
+apart from traditional programming models such as message passing
+and shared variable programming is that the execution model of
+\charmpp\ is message-driven. Therefore, computations in \charmpp\
+are triggered based on arrival of associated messages. These
+computations in turn can fire off more messages to other (possibly remote)
+processors that trigger more computations on those processors.
+
+At the heart of any \charmpp\ program is a scheduler that
+repetitively chooses a message from the available pool of messages,
+and executes the computations associated with that message.
+
+The programmer-visible entities in a \charmpp\ program are:
+
+\begin{itemize}
+\item Concurrent Objects : called {\em chares}\footnote{
+      Chare (pronounced {\bf ch\"ar}, \"a as in c{\bf a}rt) is Old 
+      English for chore.
+      }
+\item Communication Objects : messages
+\end{itemize}
+
+\charmpp\ starts a program by creating a single \index{chare} chare of
+type {\tt main} on processor 0, and envokes the constructor method 
+({\tt main}) of this chare. Typically, this chare 
+then creates a number of other \index{chare} chares, possibly on 
+other processors, which can simultaniously work to 
+solve the problem at hand.
+
+Each \index{chare}chare contains a number of 
+\index{entry method}{\em entry methods}, which 
+are methods that can be invoked from remote processors. The \charmpp\ runtime 
+system needs to be explicitly told about these methods, via 
+an {\em interface} in a separate file.
+The syntax of this interface specification file is described in the later
+sections.
+
+\charmpp\ provides system calls to asynchronously create remote \index{chare}
+chares and to asynchronously invoke entry methods on remote chares by
+sending \index{message} messages to those chares. This asynchronous 
+\index{message}message passing is the 
+basic interprocess communication mechanism in \charmpp. However, \charmpp\ 
+also permits wide variations on this mechanism to make it easy for the 
+programmer to write programs that adapt to the dynamic runtime environment. 
+These possible variations include prioritization (associating priorities with 
+method invocations), conditional \index{message packing}message packing and 
+unpacking (for reducing
+messaging overhead), \index{quiescence}quiescence detection 
+(for detecting completion of
+some phase of the program), and dynamic load balancing (during remote object
+creation). In addition, several libraries are built on top of \charmpp\
+that can simplify otherwise arduous parallel programming tasks.
+
+The following sections provide detailed information about various features
+of \charmpp\ programming system.
+
+\subsection{History}
+
+%update with history up to 5.0 version
+
+The {\sc Charm} software was developed as a group effort of the Parallel
+Programming Laboratory at the University of Illinois at Urbana-Champaign.
+The earliest prototype, Chare Kernel(1.0), was developed by Wennie Shu
+and Kevin Nomura working with Laxmikant Kale.  The second prototype,
+Chare Kernel(2.0), a complete re-write with major design changes, was
+developed by a team consisting of Wayne Fenton, Balkrishna Ramkumar,
+Vikram Saletore, Amitabh B. Sinha and Laxmikant Kale. The translator
+for Chare Kernel(2.0) was written by Manish Gupta.  {\sc Charm}(3.0), with
+significant design changes, was developed by a team consisting of
+Attila Gursoy, Balkrishna Ramkumar, Amitabh B.  Sinha and Laxmikant
+Kale, with a new translator written by Nimish Shah.  The \charmpp\
+implementation was done by Sanjeev Krishnan.  {\sc Charm}(4.0) included
+\charmpp\ and was released in fall 1993.  The translator-based version
+of the {\sc Charm} software (4.5), has been developed by Attila Gursoy,
+Sanjeev Krishnan, Milind Bhandarkar, Joshua Yelon, Narain Jagathesan
+and Laxmikant Kale.  The runtime system of {\sc Charm}(4.5) was completely
+rewritten on top of the {\sc Converse} portable parallel runtime system
+\cite{ConverseRTSPP98}, \cite{InterOpIPPS96}.  We no
+longer support the translator-based version of \charmpp. Instead, in
+its current form, \charmpp is built as a library on top of the Converse
+runtime system, with a tiny interface translator. This version of
+\charmpp, which, in earlier releases was known as {\em Interface
+Translator \charmpp}, is the default version of \charmpp\ now, and
+hence referred simply as {\bf \charmpp}.
+
+\subsection{Notation Used}
+
+Small code samples used to illustrate syntax specifications throughout
+this document will use the following typeface conventions:
+
+\begin{itemize}
+\item Language keywords appear as boldface words: \keyword{chare}.
+\item User-defined types and function names appear in a sans serif font:
+\userword{chareName}. 
+\item User-defined variables appear italicized: {\it myChare}.
+\item All other code appears in the same font as the regular text of
+this document.
+\end{itemize}
+
+Longer code samples of actual code will appear in the standard
+typewriter font. 
+
+
+
diff --git a/doc/charm++/io.tex b/doc/charm++/io.tex
new file mode 100644 (file)
index 0000000..cac682f
--- /dev/null
@@ -0,0 +1,44 @@
+\subsection{Terminal I/O}
+
+\index{input/output}
+Charm++ provides both C and C++ style methods of doing terminal I/O.  
+
+In the place of C-style printf and scanf, charm++ provides
+\index{CkPrintf}CkPrintf and \index{CkScanf}CkScanf.  These functions have
+interfaces that are identical to their C counterparts, but there are some
+differences in their behavior that should be mentioned.
+
+{\bf int CkPrintf(format [, arg]*)} \index{CkPrintf} \index{input/output} \\
+This call is used for atomic terminal output. Its usage is similar to {\sf
+printf} in C.  However, CkPrintf has some special properties that make it more
+suited for parallel programming on networks of workstations.  CkPrintf routes
+all terminal output to the processor 0, which is the one running the host
+program.  So, if a \index{chare}chare on processor 3 makes a call to CkPrintf,
+that call puts the output in a \index{message}message and sends it to processor
+0 where it will be displayed.  This message passing is an asynchronous send,
+meaning that the call to CkPrintf returns immediately after the message has
+been sent, and most likely before the message has actually been received,
+processed, and displayed. \footnote{Because of communication latencies, the
+following scenario is actually possible: Chare 1 does a Ckprintf from processor
+1, then creates chare 2 on processor 2.  After chare 2's creation, it calls
+CkPrintf, and the message from chare 2 is displayed before the one from chare
+1.}   
+
+{\bf void CkError(format [, arg]*))} \index{CkError} \index{input/output} \\
+Like CkPrintf, but used to print error messages.
+
+{\bf int CkScanf(format [, arg]*)} \index{CkScanf} \index{input/output} \\
+This call is used for atomic terminal input. Its usage is similar to
+{\sf scanf} in C.  A call to CkScanf, unlike CkPrintf, blocks all execution on
+the processor it is called from, and returns only after all input has been
+retrieved.
+
+For C++ style stream-based I/O, Charm++ offers \index{ckin}\keyword{ckin},
+\index{ckout}\keyword{ckout}, and \index{ckerr}\keyword{ckerr} in the place of
+cin, cout, and cerr.  The C++ streams and their Charm++ equivalents are related
+in the same manner as printf and scanf are to CkPrintf and CkScanf.  The
+Charm++ streams are all used through the same interface as the C++ streams, and
+all behave in a slightly different way, just like C-style I/O.  \keyword{ckout}
+and \keyword{ckerr} both have the same idiosyncratic behavior as CkPrintf, and
+\keyword{ckin} behaves in the same way as CkScanf.
+
diff --git a/doc/charm++/keywords.tex b/doc/charm++/keywords.tex
new file mode 100644 (file)
index 0000000..9f7036b
--- /dev/null
@@ -0,0 +1,98 @@
+\section{\charmpp\ Keywords}
+The following is the complete list of keywords in \charmpp:
+
+\begin{enumerate}
+\item array
+\item char
+\item chare
+\item class
+\item double
+\item entry
+\item exclusive
+\item extern
+\item float
+\item group
+\item int
+\item long
+\item mainchare
+\item mainhandle
+\item mainmodule
+\item message
+\item module
+\item nodegroup
+\item packed
+\item readonly
+\item short
+\item stacksize
+\item sync 
+\item template
+\item thisgroup
+\item thishandle
+\item threaded
+\item unsigned 
+\item varsize
+\item virtual
+\item void
+\end{enumerate}
+
+The following is the complete list of system operators and calls in \charmpp.
+Currently no user-defined functions may have one of these names.
+
+\begin{enumerate}
+\item CkAllocBuffer
+\item CkAllocMsg
+\item CkAllocSysMsg
+\item CkArgMsg
+\item CkArrayID
+\item CkBroadcastMsgBranch
+\item CkBroadcastMsgNodeBranch
+\item CkChareID
+\item CkCopyMsg
+\item CkCreateChare
+\item CkCreateGroup
+\item CkCreateNodeGroup
+\item CkError
+\item CkExit
+\item CkFreeMsg
+\item CkFreeSysMsg
+\item CkGetChareID
+\item CkGetGroupID
+\item CkGetNodeGroupID(void);
+\item CkGetRefNum
+\item CkGetSrcNode
+\item CkGetSrcPe
+\item CkLocalBranch(int groupID);
+\item CkLocalNodeBranch(int groupID);
+\item CkMyPe
+\item CkMyRank
+\item CkMyNode
+\item CkNodeFirst
+\item CkNodeOf
+\item CkNodeSize
+\item CkNumNodes
+\item CkNumPes
+\item CkPrintf
+\item CkPriorityPtr
+\item CkQdMsg
+\item CkRankOf
+\item CkRegisterChare
+\item CkRegisterEp
+\item CkRegisterMainChare
+\item CkRegisterMsg
+\item CkRegisterReadonly
+\item CkRegisterReadonlyMsg
+\item CkRemoteCall
+\item CkRemoteBranchCall
+\item CkRemoteNodeBranchCall
+\item CkScanf
+\item CkSendMsg
+\item CkSendMsgBranch
+\item CkSendMsgNodeBranch
+\item CkSendToFuture
+\item CkSetQueueing
+\item CkSetRefNum
+\item CkStartQD
+\item CkTimer
+\item CkWaitQd
+\item CkWallTimer
+\end{enumerate}
diff --git a/doc/charm++/manual.tex b/doc/charm++/manual.tex
new file mode 100644 (file)
index 0000000..2134499
--- /dev/null
@@ -0,0 +1,118 @@
+\documentclass[11pt]{article}
+\usepackage{fullpage}
+\pagestyle{headings}
+\setlength{\parskip}{0.1in}
+\setlength{\textheight}{9.5in}
+\setlength{\textwidth}{6.5in}
+\setlength{\parindent}{0in}
+\setlength{\topmargin}{-.5in}
+\parskip 0.1in
+
+%
+% Constants
+%
+\newcommand{\version}{5.0}             %%% The current version number
+\newcommand{\prevversion}{4.9} %%% The previous version number
+
+%
+% Commands
+%
+\newcommand{\zap}[1]{ }
+\newcommand{\fcmd}{\bf}                %%% Font for Charm commands
+\newcommand{\fparm}{\it\sf}    %%% Font for parameters to Charm commands
+\newcommand{\fexec}{\bf}       %%% Font for compile/execute cmds/options
+\newcommand{\atitle}[1]{{\it #1}}
+\newcommand{\keyword}[1]{{\textbf{#1}}}
+\newcommand{\userword}[1]{{\fparm \textsf{#1}}}
+\newcommand{\constraint}[1]{Note: {\it #1}}
+\newcommand{\note}[1]{Note: {\it #1}}
+
+%
+% Conveniences
+%
+\newcommand{\uw}[1]{\userword{#1}}
+\newcommand{\kw}[1]{\keyword{#1}}
+\newcommand{\CLocalBranch}{\keyword{CLocalBranch}}
+
+%
+%       \CC gives "C++" that looks good.
+%
+\newcommand{\CC}{C\kern -0.0em\raise 0.5ex\hbox{\normalsize++}}
+\newcommand{\emCC}{C\kern -0.0em\raise 0.4ex\hbox{\normalsize\em++}}
+\newcommand{\charmpp}{{\sc Charm++}}
+
+\makeindex
+
+\begin{document}
+
+\begin{titlepage}
+\vspace*{2in}
+\Huge
+\begin{center}
+The \\
+\charmpp \\
+Programming Language \\
+Manual\\
+\vspace*{0.5in}
+Version 5.0\\
+\vspace*{0.7in}
+\today
+\end{center}
+\normalsize
+\end{titlepage}
+
+\input{ack}
+
+\newpage
+\tableofcontents
+
+\newpage
+\input{intro}
+
+\newpage
+\input{overview}
+
+\section{The \charmpp\ Language}
+  \input{modules}      
+  \input{messages}
+  \input{seqobjs}
+  \input{chares}
+  \input{groups}
+  \input{nodegroups}
+  \input{arrays}
+  \input{readonly}    
+  \input{quiesce}    
+  \input{io}
+  \input{othercalls}    
+
+\newpage
+\input{inhertmplt}
+
+\newpage
+\appendix
+
+\input{comprundebug}
+
+\input{keywords}
+
+\input{syntaxchange}
+
+\input{sdag}
+
+\input{idl}
+
+\input{further}
+  \input{related}
+  \input{tools}
+  \input{contacts}
+
+\newpage
+\addtocontents{toc}{\contentsline {section}{\numberline {}References}{46}}
+\bibliographystyle{plain}
+\bibliography{group}
+
+\newpage
+\addtocontents{toc}{\contentsline {section}{\numberline {}Index}{47}}
+\include{index}
+
+\end{document}
diff --git a/doc/charm++/messages.tex b/doc/charm++/messages.tex
new file mode 100644 (file)
index 0000000..4112f6d
--- /dev/null
@@ -0,0 +1,524 @@
+\subsection{Messages}
+
+In \charmpp, \index{chare}chares and \index{group}groups communicate using 
+messages. Sending a message \index{message} to an object corresponds to an 
+asynchronous method invocation.
+
+Message definitions are very similar to class definitions in C++. 
+
+In the {\tt .ci} file (the interface file), a message is declared as: 
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{message} \uw{MessageType};
+\end{tabbing}
+
+In the {\tt .h} file, message definition has the form:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{class} \uw{MessageType} : \kw{public CMessage}\_\uw{MessageType} \{ \\
+\> \>  // List of data and function members as in C++ \\
+\> \};
+\end{tabbing}
+
+\subsubsection{Message Creation and Deletion}
+\label{memory allocation}
+
+\index{message}Messages are allocated using the \CC\ \kw{new}\index{new}
+operator as usual :
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \uw{MessageType} *{\it msgptr} = \\
+\> \> \kw{new} [((\kw{int} *){\it sizes\_array}, \kw{int} {\it priobits}=0)] \uw{MessageType}[(constructor arguments)]; \\
+\end{tabbing}
+
+For example, to allocate a \index{varsize message}varsize message like:
+
+\begin{verbatim}
+message VarsizeMessage {
+  int length;
+  int firstArray[VARSIZE];
+  double secondArray[VARSIZE];
+};
+\end{verbatim}
+
+assign the size array and allocate the message:
+\begin{verbatim}
+int size[2];
+size[0] = 10;
+size[1] = 20;
+VarsizeMessage *msg = new (size) VarsizeMessage;
+\end{verbatim}
+
+To give the integer \index{priority}priority to this message, 
+\begin{verbatim}
+VarsizeMessage *msg = new (size, sizeof(int)*8) VarsizeMessage;
+\end{verbatim}
+Note, you must provide number of bits which is used to store the priority as the {\it priobits} parameter.
+
+In Section~\ref{message packing} we explain how messages can
+contain arbitrary pointers, and how the validity of such pointers can be
+maintained across processors in a distributed memory machine.
+
+When a message \index{message} is sent to a \index{chare}chare, the programmer
+relinquishes control of it; the space allocated to the message is
+freed by the system.  When a message is received at an entry point it
+is not freed by the runtime system.  It may be reused or deleted by
+the programmer.  Messages can be deleted using the standard C++
+\kw{delete}\index{delete} operator.  
+
+
+\subsubsection{Entry Method Attributes}
+\label{attributes}
+
+Charm++ provides a handful of special attributes that \index{entry method}entry
+methods may have.  In order to give a particular \index{entry method}entry
+method an attribute, you must specify the keyword for the desired attribute in
+the attribute list of that entry method's .ci file declaration.  The syntax for
+this is as follows:
+
+\small
+\keyword{entry} \userword{[attribute1, ..., attributeN] void EntryMethod(MessageType *)};
+\normalsize
+
+Charm++ currently offers four attributes that one may give an entry method:
+threaded, sync, exclusive, and virtual.
+\index{threaded}\index{sync}\index{exclusive}\index{virtual}
+
+\index{threaded}Threaded \index{entry method}entry methods are simply entry
+methods which are run in their own nonpremptible threads.  To make an
+\index{entry method}entry method threaded, one simply adds the keyword
+\keyword{threaded} to the attribute list of that entry method.
+
+\index{sync}Sync \index{entry method}entry methods are special in that calls to
+sync entry methods are blocking - they do not return control to the caller
+until the method is finished executing completely.  Sync methods may have
+return values; however, they may only return messages.  To make an \index{entry
+method}entry method a sync entry method, add the keyword \keyword{sync} to the
+attribute list of that entry method.
+
+\index{exclusive}Exclusive entry methods, which exist only on node groups, are
+\index{entry method}entry methods that do not execute while other exclusive
+\index{entry method}entry methods of its node group are executing in the same
+node.  If one exclusive method of a node group is executing on node 0, and
+another one is scheduled to run on that same node, the second exclusive method
+will wait for the first to finish before it executes.  To make an \index{entry
+method}entry method exclusive, add the keyword \keyword{exclusive} to that
+entry method's attribute list.
+
+\index{virtual}Virtual \index{entry method}entry methods are inherited in the
+same manner as virtual methods of sequential C++ objects.  For a detailed
+discussion of inheritance in Charm++, refer to section \ref{inheritance and
+templates}.  To make an entry method virtual, just add the keyword
+\keyword{virtual} to that method's attribute list.  Additionally, one may make
+a virtual \index{entry method}entry method a pure virtual entry method.  They
+behave in the same way as pure virtual methods in C++ and are declared in a
+very similar fashion.  To make a virtual entry method pure, add a ``= 0'' after
+that entry method's .ci file declaration.  This looks like the following:
+
+\small
+\keyword{entry} \userword{[virtual] void PureVirtualEntry(MessageType *) = 0};
+\normalsize
+
+
+
+\subsubsection{Message Packing}
+\label{message packing}
+\index{message packing}
+\index{packed messages}
+
+When one declares \charmpp\ messages in the ``.ci'' file, the
+translator generates code to register those messages along with their
+size with the runtime system. This information is later used to
+efficiently allocate messages by the runtime system.
+
+In many cases, the messages store {\em non-linear} data structures
+using pointers.  Examples of these are binary trees, hash tables
+etc. Thus, the message itself contains only a pointer to the actual
+data. When the message is sent to the same processor, these pointers
+point to the original locations, which are within the address space of
+the same processor, however, when such a message is sent to other
+processors, these pointers will point to invalid locations.
+
+Thus, the programmer needs a way to ``serialize'' these messages
+\index{serialized messages}\index{message serialization}{\em
+only if} the message crosses the address-space boundary. This is
+provided in \charmpp\ using
+\kw{packed} \index{packed} messages.
+
+Such messages are declared in the {\tt .ci} file as:
+
+\verb+message [packed] PMessage;+
+
+The class \uw{PMessage} needs to inherit from \uw{CMessage\_PMessage}
+and needs to provide two {\em static} methods: \kw{pack}, \index{pack}
+and \kw{unpack}\index{unpack}. These methods are called by the
+\charmpp\ runtime system, when the message is determined to be
+crossing address-space boundary. The prototypes for these methods are
+as follows:
+
+\begin{verbatim}
+static void *PMessage::pack(PMessage *in);
+static PMessage *PMessage::unpack(void *in);
+\end{verbatim}
+
+Typically, the following tasks are done in \kw{pack} method:
+
+\begin{itemize}
+\item Determine size of the buffer needed to serialize message data.
+\item Allocate buffer using the \kw{CkAllocBuffer}
+\index{CkAllocBuffer} function. This
+function takes in two parameters: input message, and size of the
+buffer needed, and returns the buffer.
+\item Serialize message data into buffer (alongwith any control
+information needed to de-serialize it on the receiving side.
+\item Free resources occupied by message (including message itself.)  
+\end{itemize}
+
+On the receiving processor, the \kw{unpack} method is
+called. Typically, the following tasks are done in the \kw{unpack}
+method:
+
+\begin{itemize}
+\item Allocate message using \kw{CkAllocBuffer} function. {\em Do not
+use \kw{new} to allocate message here. If the message constructor has
+to be called, it could be done using the in-place \kw{new} \index{new}
+operator.}
+\item De-serialize message data from input buffer into the allocated message.
+\item Free the input buffer using \kw{CkFreeMsg}\index{CkFreeMsg}.
+\end{itemize}
+
+Here is an example of a {\em packed} message implementation:
+
+\begin{verbatim}
+// File: pgm.ci
+module PackExample {
+  ...
+  message [packed] PackedMessage;
+  ...
+};
+
+// File: pgm.h
+...
+class PackedMessage : public CMessage_PackedMessage
+{
+  public:
+    BinaryTree<NodeType> *btree; // Non-linear data structure
+    static void *pack(PackedMessage *);
+    static PackedMessage *unpack(void *);
+    ...
+};
+...
+
+// File: pgm.C
+...
+void *
+PackedMessage::pack(PackedMessage *inmsg)
+{
+  int numnodes = inmsg->btree->numNodes();
+  int totalsize = numnodes*sizeof(NodeType) + sizeof(int);
+  int *buf = (int *)CkAllocBuffer(inmsg, totalsize);
+  *buf++ = numnodes;
+  inmsg->btree->flatten((void *)buf); // copies nodes, and 
+                                      // replaces pointers by indices
+  delete inmsg;
+  return (void *)(--buf);
+}
+
+PackedMessage *
+PackedMessage::unpack(void *inbuf)
+{
+  int *buf = (int *)inbuf;
+  int numnodes = *buf++;
+  PackedMessage *pmsg = CkAllocBuffer(inbuf, sizeof(PackedMessage));
+  pmsg = new ((void *)pmsg) PackedMessage(inbuf, numnodes); // constructs btree
+  CkFreeMsg(inbuf);
+}
+... 
+}
+\end{verbatim}
+
+While serializing an arbitrary data structure into a flat buffer, one
+must be very wary of any possible alignment problems.  Thus, if
+possible, the buffer itself should be declared to be a flat struct.
+This will allow the \CC\ compiler to ensure proper alignment of all
+its member fields.
+
+\subsubsection{Variable Size Messages}
+\label{varsize messages}
+\index{variable size messages}
+\index{varsize message}
+
+An ordinary message in \charmpp\ is a fixed size message that is
+allocated internally with an envelope which encodes the size of the
+message. Very often, the size of the data contained in a message is
+not known until runtime. One can use \kw{packed}\index{packed
+messages} messages to alleviate 
+this problem. However, it requires multiple memory allocations (one
+for the message, and another for the buffer.) This can be avoided by
+making use of a \kw{varsize}\index{varsize} message.
+
+A \kw{varsize} message is declared as {\tt message [varsize] mtype} in
+\charmpp\ interface file. The class \uw{mtype} has to inherit from
+\uw{CMessage\_mtype} AND has to provide \kw{pack}\index{pack},
+\kw{unpack}\index{unpack}, AND
+\kw{alloc}\index{alloc} class methods.
+
+Thus, a varsize message is declared in the interface as: 
+
+\verb+message [varsize] MyVarsizeMessage;+ 
+
+In the \CC\ header file, it has to be defined as: 
+
+\begin{verbatim}
+class MyVarsizeMessage : public CMessage_MyVarsizeMessage { 
+// Other methods & data members 
+  static void *alloc(int msgnum, size_t size, int *array, int priobits); 
+  static void* pack(msg* in); 
+  static msg* unpack(void* in); 
+}; 
+\end{verbatim}
+
+The \kw{alloc} method should actually allocate the message using
+\kw{CkAllocMsg}\index{CkAllocMsg}, whose signature is given below:
+
+\begin{verbatim}
+void *CkAllocMsg(int msgnum, int size, int priobits); 
+\end{verbatim}  
+
+{\bf An Example:}
+
+Suppose a \charmpp\ message contains two varsize fields 
+(denoted here using an old keyword VARSIZE):
+
+\begin{verbatim} 
+message VarsizeMessage { 
+  int length; 
+  int firstArray[VARSIZE]; 
+  double secondArray[VARSIZE]; 
+}; 
+\end{verbatim}
+
+Then in \charmpp, this can be represented as: 
+
+\begin{verbatim}
+message [varsize] NewVarsizeMessage; 
+
+class NewVarsizeMessage : public CMessage_NewVarsizeMessage { 
+  public: 
+    int len; 
+    int *firstArray; 
+    double *secondArray; 
+
+  static void *alloc(int msgnum, int size, int *array, int priobits) 
+  { 
+    int totalsize; 
+    totalsize = size + array[0]*sizeof(int) + array[1]*sizeof(double); 
+    NewVarsizeMessage *newMsg = 
+      (NewVarsizeMessage *) CkAllocMsg(msgnum, totalsize, priobits); 
+    newMsg->firstArray = (int *) ((char *)newMsg+size); 
+    newMsg->secondArray = (double *) ((char *)newMsg + size + 
+                                      sizeof(int)*array[0]); 
+    return (void *)newMsg; 
+  } 
+
+  static void *pack(NewVarsizeMessage *in) 
+  { 
+    in->firstArray = (int *) ((char *) in->firstArray - 
+                              (char *)&in->firstArray); 
+    in->secondArray = (double *) ((char *) in->secondArray - 
+                                  (char *) &in->secondArray); 
+    return in; 
+  } 
+
+  static NewVarsizeMessage* unpack(void *in) 
+  { 
+    NewVarsizeMessage *me = (NewVarsizeMessage *) in; 
+    me->firstArray = (int *) ((char *) &(me->firstArray) + 
+                              (size_t)(me->firstArray)); 
+    me->secondArray = (double *) ((char *) &(me->secondArray) + 
+                                  (size_t)(me->secondArray)); 
+    return me;
+  } 
+}; 
+\end{verbatim}
+
+The pointers in a varsize message can exist in two states.  
+At creation, they are valid \CC\ pointers to the start of the arrays.  
+After packing, they become offsets from the address of the pointer variable to 
+the start of the pointed-to data.  Unpacking restores them to pointers. 
+
+\subsubsection{Prioritized Execution}
+\label{prioritized message passing}
+\index{prioritized execution}
+\index{prioritized message passing}
+\index{priorities}
+
+By default, \charmpp\ will process the messages you send in roughly
+FIFO\index{message delivery order} order.  For most programs, this
+behavior is fine.  However, some programs need more explicit control
+over the order in which messages are processed.  \charmpp\ allows you
+to control queueing behavior on a per-message basis.
+
+The simplest call available to change the order in which messages
+are processed is \kw{CkSetQueueing}\index{CkSetQueueing}.
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{void CkSetQueueing}(\uw{MsgType} {\it message}, \kw{int} {\it
+queueingtype}) \\
+\end{tabbing}
+
+where {\it queueingtype}\index{queueing types} is one of the following
+constants:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{CK\_QUEUEING\_FIFO}\\
+\> \kw{CK\_QUEUEING\_LIFO}\\
+\> \kw{CK\_QUEUEING\_IFIFO}\\
+\> \kw{CK\_QUEUEING\_ILIFO}\\
+\> \kw{CK\_QUEUEING\_BFIFO}\\
+\> \kw{CK\_QUEUEING\_BLIFO}\\
+\index{CK\_QUEUEING\_FIFO}
+\index{CK\_QUEUEING\_LIFO}
+\index{CK\_QUEUEING\_IFIFO}
+\index{CK\_QUEUEING\_ILIFO}
+\index{CK\_QUEUEING\_BFIFO}
+\index{CK\_QUEUEING\_BLIFO}
+\end{tabbing}
+
+The first two options,  \kw{CK\_QUEUEING\_FIFO} and
+\kw{CK\_QUEUEING\_LIFO}, are used as follows: 
+
+\begin{verbatim}
+  MsgType *msg1 = new MsgType ;
+  CkSetQueueing(msg1, CK_QUEUEING_FIFO);
+
+  MsgType *msg2 = new MsgType ;
+  CkSetQueueing(msg2, CK_QUEUEING_LIFO);
+\end{verbatim}
+
+When message {\tt msg1} arrives at its destination, it will be pushed
+onto the end of the message queue as usual.  However, when {\tt msg2}
+arrives, it will be pushed onto the {\it front} of the message queue.
+
+The other four options involve the use of
+priorities\index{priorities}.  To attach a priority field to a
+message, one needs to set aside space in the message's buffer while
+allocating the message\index{message priority}.  To achieve this, the
+size of the priority field\index{priority field} in bits should be
+specified as a placement argument to the \kw{new} operator, as
+described in Section \ref{memory allocation}.  Although the size of
+the priority field is specified in bits, it is always padded to an
+integral number of {\tt int}s.  A pointer to the priority part of the
+message buffer can be obtained with these calls:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{unsigned int} *\kw{CkPriorityPtr}(\uw{MsgType} {\it msg}) \\
+\end{tabbing}
+\index{CkPriorityPtr}
+\index{priority pointer}
+
+There are two kinds of priorities which can be attached to a message:
+{\sl integer priorities}\index{integer priorities} and {\sl bitvector
+priorities}\index{bitvector priorities}.  Integer priorities are quite
+straightforward.  One allocates a message, setting aside enough space
+(in bits) in the message to hold the priority, which is an integer.
+One then stores the priority in the message.  Finally, one informs the
+system that the message contains an integer priority using
+\kw{CkSetQueueing}:
+
+\begin{verbatim}
+  MsgType *msg = new (8*sizeof(int)) MsgType;
+  *CkPriorityPtr(msg) = prio;
+  CkSetQueueing(msg, CK_QUEUEING_IFIFO);
+\end{verbatim}
+\index{CkSetQueueing}
+
+The predefined constant  \kw{CK\_QUEUEING\_IFIFO} indicates that the
+message contains an integer priority, and that if there are other
+messages of the same priority, they should be sequenced in FIFO order
+(relative to each other).  Similarly, a  \kw{CK\_QUEUEING\_ILIFO} is
+available.  Note that  \kw{MAXINT} is the lowest priority, and {\bf
+NEGATIVE\_MAXINT} is the highest priority\index{integer priority range}.
+
+Bitvector priorities are somewhat more complicated.  Bitvector
+priorities are arbitrary-length bit-strings representing fixed-point
+numbers in the range 0 to 1.  For example, the bit-string ``001001''
+represents the number .001001\raisebox{-.5ex}{\scriptsize binary}.  As
+with the simpler kind of priority, higher numbers represent lower
+priorities.  Unlike the simpler kind of priority, bitvectors can be of
+arbitrary length, therefore, the priority numbers they represent can
+be of arbitrary precision.
+
+Arbitrary-precision priorities\index{arbitrary-precision priorities}
+are often useful in AI search-tree applications.  Suppose we have a
+heuristic suggesting that tree node $N_1$ should be searched before
+tree node $N_2$.  We therefore designate that node $N_1$ and its
+descendants will use high priorities, and that node $N_2$ and its
+descendants will use lower priorities.  We have effectively split the
+range of possible priorities in two.  If several such heuristics fire
+in sequence, we can easily split the priority range \index{priority
+range splitting} in two enough times that no significant bits remain,
+and the search begins to fail for lack of meaningful priorities to
+assign.  The solution is to use arbitrary-precision priorities,
+i.e. bitvector priorities.
+
+To assign a bitvector priority, two methods are available.  The
+first is to obtain a pointer to the priority field using  \kw{CkPriorityPtr},
+and to then manually set the bits using the bit-setting operations
+inherent to C.  To achieve this, one must know the format
+\index{bitvector format} of the
+bitvector, which is as follows: the bitvector is represented as an
+array of unsigned integers.  The most significant bit of the first
+integer contains the first bit of the bitvector.  The remaining bits
+of the first integer contain the next 31 bits of the bitvector.
+Subsequent integers contain 32 bits each.  If the size of the
+bitvector is not a multiple of 32, then the last integer contains 0
+bits for padding in the least-significant bits of the integer.
+
+The second way to assign priorities is only useful for those who are
+using the priority range-splitting\index{priority range splitting}
+described above.  The root of the tree is assigned the null
+priority-string.  Each child is assigned its parent's priority with
+some number of bits concatenated.  The net effect is that the entire
+priority of a branch is within a small epsilon of the priority of its
+root.
+
+It is possible to utilize unprioritized messages, integer priorities,
+and bitvector priorities in the same program.  The messages will be
+processed in roughly the following order\index{multiple priority types}:
+
+\begin{itemize}
+
+\item Among messages enqueued with bitvector priorities, the
+messages are dequeued according to their priority.  The
+priority ``0000...'' is dequeued first, and ``1111...'' is
+dequeued last.
+
+\item Unprioritized messages are treated as if they had the
+priority ``1000...'' (which is the ``middle'' priority, it
+lies exactly halfway between ``0000...'' and ``1111...'').
+\item Integer priorities are converted to bitvector priorities.  They
+are normalized so that the integer priority of zero is converted to
+``1000...'' (the ``middle'' priority).  To be more specific, the
+conversion is performed by adding 0x80000000 to the integer, and then
+treating the resulting 32-bit quantity as a 32-bit bitvector priority.
+
+\item Among messages with the same priority, messages are
+dequeued in FIFO order or LIFO order, depending upon which
+queuing strategy was used.
+
+\end{itemize} 
+
+A final warning about prioritized execution: \charmpp\ always processes
+messages in {\it roughly} the order you specify; it never guarantees to
+deliver the messages in {\it precisely} the order\index{message
+delivery order} you specify.
+However, it makes a serious attempt to be ``close'', so priorities
+can strongly affect the efficiency of your program.
diff --git a/doc/charm++/modules.tex b/doc/charm++/modules.tex
new file mode 100644 (file)
index 0000000..fa15a73
--- /dev/null
@@ -0,0 +1,133 @@
+\subsection{Modules}
+
+\subsubsection{Structure of a \charmpp\ Program}
+
+A \charmpp\ program is structurally similar to a C++ program.  Most of
+a \charmpp\ program {\em is} C++ code
+\footnote{\bf Constraint: The C++ code cannot, however,
+contain global or static variables.}. The main syntactic units in a
+\charmpp\ program are class definitions. A \charmpp\ program can
+be distributed across several source code files.
+
+There are five disjoint categories of objects (classes) in \charmpp:
+\begin{itemize}
+\item Sequential objects: as in C++
+\item Chares (concurrent objects) \index{chare}
+\item Chare Groups \index{chare groups} (a form of replicated objects)
+\index{group}
+\item Chare Arrays \index{chare arrays} (an indexed collection of chares)
+\index{array}
+\item Messages (communication objects)\index{message}
+\end{itemize}
+
+The user's code is written in C++ and interfaces with the \charmpp\
+system as if it were a library containing base classes, functions, etc.
+A translator is used to generate the special code needed to handle
+\charmpp\ constructs.  This translator generates C++ code that needs
+to be compiled with the user's code.
+
+Interfaces to the \charmpp\ objects (such as messages, chares, readonly 
+variable etc.) \index{message}\index{chare}\index{readonly}
+have to be declared in \charmpp\ interface files. Typically, such entities 
+are grouped \index{module}
+into {\em modules}. A \charmpp\ program may consists of multiple modules. 
+One of these modules
+is declared to be a \kw{mainmodule}. All the modules that are
+``reachable'' from the \kw{mainmodule} via the \kw{extern} construct
+are included in a \charmpp\ program.
+
+The \charmpp\ interface file as the suffix ``.ci''. 
+The \charmpp\ interface translator parses this file and produces two files 
+(with suffixes ``.decl.h'' and ``.def.h'') that contain declarations 
+(interface) and definitions (implementation)
+of various translator-generated entities. If the name of a
+module is \uw{MOD}, then the files produced by the \charmpp\ interface translator 
+are named \uw{MOD.decl.h} and \uw{MOD.def.h}\footnote{Note that the interface 
+file for module \uw{MOD} need not be named \uw{MOD.ci}. Indeed one ``.ci'' 
+file may contain interface declarations for multiple modules, and the 
+translator will produce one pair of declaration and definition files for each 
+module.}.  We recommend that the declarations header file be included at the 
+top of the header file (\uw{MOD.h}) for module \uw{MOD}, and the definitions 
+file be included at the bottom of the code for module (\uw{MOD.C})
+\footnote{In the earlier version of interface translator, these files used to 
+be suffixed with ``.top.h'' and ``.bot.h'' for this reason.}.
+
+A simple \charmpp\ program is given below:
+
+\begin{verbatim}
+///////////////////////////////////////
+// File: pgm.ci
+
+module Hello {
+  mainchare HelloMain {
+    entry HelloMain(); // implicit CkArgMsg * as argument
+    entry [threaded] void Wait(void);
+  };
+  group HelloGroup {
+    entry HelloGroup(void);
+  } 
+};
+
+////////////////////////////////////////
+// File: pgm.h
+#include "Hello.decl.h" // Note: not pgm.decl.h
+
+class HelloMain: public Chare {
+  HelloMain(CkArgMsg *);
+  void Wait(void);
+};
+
+class HelloGroup: public Group {
+  HelloGroup(void);
+};
+
+/////////////////////////////////////////
+// File: pgm.C
+#include "pgm.h"
+
+HelloMain::HelloMain(CkArgMsg *msg) {
+  delete msg;
+  CProxy_HelloGroup::ckNew(); //Create a new ``HelloGroup''
+  CProxy_HelloMain pself(thishandle);
+  pself.Wait();
+}
+
+void HelloMain::Wait(void) {
+  CkWaitQD(); //Waits for ``quiescence''
+  CkExit();
+}
+
+HelloGroup::HelloGroup(void) {
+  ckout << "Hello World from processor " << CkMyPe() << endl;
+}
+
+#include "Hello.def.h" //Include the Charm++ object implementations
+
+/////////////////////////////////////////
+// File: Makefile
+
+pgm: pgm.ci pgm.h pgm.C
+      charmc -c pgm.ci
+      charmc -c pgm.C
+      charmc -o pgm pgm.o -language charm++
+
+\end{verbatim}
+
+\uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm Kernel starts 
+execution of this program by creating an instance of \uw{HelloMain} on 
+processor 0. The HelloMain constructor creates a chare group \uw{HelloGroup}, and 
+calls \uw{Wait} on itself asynchronously.  Both these calls return immediately
+after directing Charm Kernel to perform the actual creation and invocation. 
+Shortly after, the Charm Kernel will create an object of type
+\uw{HelloGroup} on each processor, which will print out 
+``Hello World...''.  The \uw{Wait} method 
+of \uw{HelloMain} may simultainously be invoked, which  
+will wait for quiescence (no activity in 
+the program) and then it will exit the program.
+
+
+
+
+
+
+
diff --git a/doc/charm++/nodegroups.tex b/doc/charm++/nodegroups.tex
new file mode 100644 (file)
index 0000000..f890b4f
--- /dev/null
@@ -0,0 +1,66 @@
+\subsection{Nodegroup Objects}
+
+{\it Node groups} \index{node groups} \index{nodegroup} are very
+similar to the group objects already discussed in that node groups are
+collections of chares as well.  Node groups, however, have one chare
+per node rather than one chare per processor.
+So, each node contains a branch of the node group, each containing one
+set of data members.  When an entry method of a node group is
+executed, it runs on only one processor within each
+node.
+
+Node groups have a definition syntax that is very similar to groups.  Rather
+than inheriting from the system defined class, \kw{Group}, node groups 
+inherit from \kw{Nodegroup}.  For example, in the interface file, we declare:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{nodegroup} \uw{NodegroupType} \{ \\
+\> \> // Interface specifications as for normal chares \\
+\> \};
+\end{tabbing}
+
+In the {\tt .h} file, we define \uw{NodeGroupType} as follows:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{class} \uw{NodeGroupType} : \kw{public Nodegroup} [,other
+superclasses ] \{ \\
+\> \> // Data and member functions as in C++ \\
+\> \> // Entry functions as for normal chares \\
+\> \};
+\end{tabbing}
+
+Like groups, nodegroups are identified by a globally unique identifier
+of type \index{CkGroupID}\kw{CkGroupID}.  Just like with groups, this 
+identifier is
+common to all branches of the nodegroup and can be obtained from the
+variable \index{thisgroup}\kw{thisgroup}, and once again, \index{thishandle}
+\kw{thishandle} is the handle of the particular branch in which the function 
+is executing.
+
+Node groups may possess \index{exclusive}\keyword{exclusive} entry methods.  
+These are entry methods that will not run while other other exclusive entry 
+methods of that node group are running on the same node.  For instructions 
+for making an entry method exclusive, refer to section \ref{attributes}.
+
+For certain applications, node groups can be used in the place of
+regular groups to cut down on messaging overhead when shared memory
+access is possible.  For example, consider a parallel program that
+does one calculation that can be decomposed into several mutually
+exclusive subcalculations.  The program distributes the work amongst
+all of the processors, the subresults are all stored in the local
+branch of a group, and when the local branch has recieved all of its
+results, it relays everything to one particular processor where the
+subresults are put together into the final result.  When normal groups
+are used, the number of messages sent is $O$(\# of processors).
+However, if node groups are used, a number of message sends will be
+replaced by local memory accesses if there is more than
+one processor per node.  Instead, the number of messages sent is
+$O$(\# of nodes).
+
+Just like groups, there can be many instances corresponding to a single node
+group type, and each instance has a different group handle, and its own set of
+branches.
+
+
diff --git a/doc/charm++/othercalls.tex b/doc/charm++/othercalls.tex
new file mode 100644 (file)
index 0000000..9373d3f
--- /dev/null
@@ -0,0 +1,64 @@
+\subsection{Other Calls}
+
+\label{other Charm++ calls}
+
+The following calls provide information about the machines upon which the
+parallel program is executing.  Processing Element refers to a single CPU.
+Node refers to a single machine-- a set of processing elements which share
+memory (i.e. an address space).  Processing Elements and Nodes are numbered,
+starting from zero.
+
+Thus if a parallel program is executing on one 4-processor workstation and one
+2-processor workstation, there would be 6 processing elements (0, 1 ,2, 3, 4,
+and 5) but only 2 nodes (0 and 1).  A given node's processing elements are
+numbered sequentially.
+
+{\bf int CkNumPes()} \index{CkNumPes} \\
+returns the total number of processors, across all nodes.
+
+{\bf int CkMyPe()} \index{CkMyPe} \\
+returns the processor number on which the call was made.
+
+{\bf int CkMyRank()} \index{CkMyRank} \\
+returns the rank number of the processor on which the call was made.
+Processing elements within a node are ranked starting from zero.
+
+{\bf int CkMyNode()} \index{CkMyNode} \\
+returns the address space number (node number) on which the call was made.
+
+{\bf int CkNumNodes()} \index{CkMyNodes} \\
+returns the total number of address spaces.
+
+{\bf int CkNodeFirst(int node)} \index{CkNodeFirst} \\
+returns the processor number of the first processor in this address space.
+
+{\bf int CkNodeSize(int node)} \index{CkNodeSize} \\
+returns the number of processors in the address space on which the call was made.
+
+{\bf int CkNodeOf(int pe)} \index{CkNodeOf} \\
+returns the node number on which the call was made.
+
+{\bf int CkRankOf(int pe)} \index{CkRankOf} \\
+returns the rank of the given processor within its node.
+
+The following calls provide commonly needed functions.
+
+{\bf void CkAbort(const char *message)} \index{CkAbort} \\
+Cause the program to abort, printing the given error message.
+
+{\bf void CkExit()} \index{CkExit} \\
+This call informs the Charm kernel that computation on all processors should 
+terminate.  After the currently executing entry method completes, no more 
+messages or entry methods will be called.  \keyword{CkExit()} should be the 
+last statement of the entry method from which it was called. 
+
+{\bf int CkTimer()} \index{CkTimer} \index{timers} \\
+returns the current value of the system timer in milliseconds. The system
+timer is started when \\
+the program begins execution. This timer measures
+process time (user and system).
+
+{\bf double CkWallTimer()} \index{CkWallTimer} \index{timers} \\
+returns the elapsed time since the program has started from the wall clock 
+timer.
+
diff --git a/doc/charm++/overview.tex b/doc/charm++/overview.tex
new file mode 100644 (file)
index 0000000..71d80ef
--- /dev/null
@@ -0,0 +1,184 @@
+\section{Charm++ Overview}
+
+\subsection{\charmpp\ Execution Model}
+
+A \charmpp\ program consists of a number of \charmpp\ objects distributed across
+the available number of processors. Thus,
+the basic unit of parallel computation in \charmpp\ programs is the
+{\em chare}\index{chare}, a \charmpp\ object that can be
+created on any available processor and can be accessed from remote processors.
+A \index{chare}chare is similar to a
+process, an actor, an ADA task, etc.  \index{chare}Chares 
+are created dynamically, and many chares
+may be active.  Chares send \index{message}{\em messages} to one another 
+to invoke methods asynchronously.  Conceptually, the system maintains a
+``work-pool'' consisting of seeds for new \index{chare}chares, and 
+\index{message}messages for
+existing chares. The runtime system (called {\em Charm Kernel}) may pick 
+multiple items,
+non-deterministically, from this pool and execute them.  It will not
+process two messages for the same \index{chare}chare concurrently, but 
+otherwise it is free to schedule them in any way.
+
+Methods of a \index{chare}chare that can be remotely invoked are called 
+\index{entry method}{\em entry} methods.
+Entry methods may take a pointer to a message object, or no parameters.
+Since \index{chare}chares can be created on remote processors, obviously 
+some constructor of a chare needs to be an entry method.
+
+\charmpp\ provides dynamic seed-based load balancing. Thus location 
+(processor number)
+need not be specified while creating a remote \index{chare}chare. The Charm Kernel
+will then place
+the remote chare on a least loaded processor. Thus one can imagine chare 
+creation as
+generating only a seed for the new chare, which may {\em take root} on the most
+{\em fertile} processor. Charm Kernel identifies a \index{chare}chare by a 
+{\em ChareID}.
+Since user code does not need to name a chares' processor, chares 
+can potentially migrate from one processor to another.
+(This behaviour is used by the dynamic load-balancing framework for 
+chare containers, such as arrays.)
+
+Other \charmpp\ objects are collections of chares. They are:
+\index{group}{\em chare-groups}, \index{nodegroup}{\em chare-nodegroups}, and
+\index{array}{\em chare-arrays}, referred to as {\em groups}, 
+{\em nodegroups}, and
+{\em arrays} throughout this manual. A group (nodegroup) is a collection of 
+chares, one per processor (SMP node),
+that is addressed using a unique system-wide name. An array is a collection 
+of arbitrary
+number of migratable chares, mapped to processors according to a user-defined 
+map group.
+
+Every \charmpp\ program must have at least one \kw{mainchare}.
+There can be only one instance of this \index{chare}, which is created on 
+processor 0 when the \charmpp\ program starts up.
+Execution of a \charmpp\ program begins with Charm Kernel constructing all the
+designated \kw{mainchare}s.  Typically, the \kw{mainchare} constructor
+starts the computation by creating other chares and chare \index{group}
+groups.  It can also be used to initialize shared \kw{readonly} objects.
+
+The only method of communication between processors in \charmpp\ is 
+asynchronous \index{entry method}
+entry method invocation on remote chares. For this purpose, Charm Kernel needs
+to know about the types of \index{chare}chares in the user program, the 
+methods that can
+be invoked on these chares from remote processors, the arguments these methods
+take as input etc. Therefore, when the program starts up, these user-defined
+entities need to be registered with Charm Kernel, which assigns a unique
+identifier to each of them. While invoking a method on a remote object, these 
+identifiers need to be specified to Charm Kernel. Registration of user-defind 
+entities, and maintaining these identifiers can be cumbersome. Fortunately, 
+it can be done
+by the \charmpp\ interface translator. The \charmpp\ interface translator 
+generates
+definitions for {\em proxy} objects. A proxy object acts as a {\em handle} to 
+a remote
+chare. One invokes methods on a proxy object, which in turn carries out remote
+method invocation on the chare.
+
+In addition, the \charmpp\ interface translator provides ways to enhance the basic
+functionality of Charm Kernel using user-level threads and futures. These allow
+entry methods to be executed in separate user-level threads. 
+These \index{threaded}
+{\em threaded} entry methods may block waiting for data by making 
+{\em synchronous} 
+calls to remote object methods that return results in messages.
+
+\charmpp\ program execution is terminated by the \index{CkExit}
+\keyword{CkExit()} call. This call is not the same as \keyword{exit()} in Unix:
+it merely informs the Charm Kernel that all computations on all
+processors must be terminated, and then returns to the user program:
+the programmer should make sure that no work is done by the method after
+\keyword{CkExit()} is called. Charm Kernel ensures that no
+messages are processed and no entry methods are called after the
+currently executing entry method completes. \keyword{CkExit()} need
+not be called on all processors; it is enough to call it from just one
+processor at the end of the computation.
+
+%The user can specify an entry method (using the \keyword{CkStartQD()}
+%\index{CkStartQD} call), to be invoked on a chare when the computation
+%has become quiescent (i.e., when no processor is executing an entry
+%method and all messages that have been sent have also been
+%consumed). This function is useful in computations where the user
+%cannot forsee when the program is going to become quiescent. It is
+%also useful for computations which proceed in phases --- the
+%quiescence entry method can be used to start new phases of
+%computation.
+
+
+\subsection{Entities in \charmpp\ programs}
+
+This section describes various entities in a typical \charmpp\ program.
+
+\subsubsection{Sequential Objects}
+
+A \charmpp\ program typically contains a number of sequential objects. These
+objects are similar to the objects in C++, except that they {\em should 
+not have any static data members}\footnote{
+  This restriction makes \charmpp\ programs portable across distributed
+  and shared memory architectures, as well as clusters of shared memory
+  multiprocessors. If one feels that these restrictions are too severe,
+  one is encouraged to look at the portability macros of Converse, that
+  make it possible to write portable programs in presence of global or
+  static variables.
+}. These objects are created synchronously
+on the local processor (using a {\tt new} operator in C++), and their
+method could be synchronously invoked only from the local processor.
+These objects are not known to the \charmpp\ runtime system, and
+thus they need not be mentioned in the module interface files.
+
+\subsubsection{Communication Objects}
+
+Communication objects (messages) supply data arguments to the
+asynchronous remote method invocation. Messages are instances of C++ classes
+that are subclassed from a special class called {\tt comm\_object}.
+These objects are treated differently from other objects in \charmpp\
+by the runtime system, and therefore they should be specified in the
+interface file of the module. They also have to be created differently
+than normal C++ objects. Another variation of communication objects
+is conditionally packed and unpacked. This variation should be used when
+one wants to send messages that contain pointers to the data rather than
+the actual data to other processors. This type of communication objects
+contains two methods: {\tt pack}, and {\tt unpack}. 
+These messages are specified differently in the interface file for the module.
+The third variation of communication objects is called {\em varsize} messages. 
+Varsize messages is an effective optimization on conditionally packed messages,
+and have to be made known to the \charmpp\ runtime using a special keyword in
+the interface file.
+
+\subsubsection{Chares}
+
+Chares are the most important entities in a \charmpp\ program. These 
+concurrent objects are different from sequential C++ objects in many
+ways. Syntactically, Chares are instances of C++ classes that are derived
+from a system-provided class called {\tt chare\_object}. Also, in addition
+to the usual C++ private and public data and method members, they contain
+some public methods called {\em entry methods}. These entry methods do not
+return anything (they are {\tt void} methods), and take exactly one argument,
+which is a pointer to a communication object. Chares are {\em accessed} using
+a handle (a structure defined in \charmpp), rather than a pointer as in C++.
+Semantically, they are different
+from C++ objects because they can be created asynchronously from remote
+processors, and their entry methods also could be invoked asynchronously
+from the remote processors. Since the constructor method is invoked
+from remote processor (while creating a chare), every chare should have
+its constuctors as entry methods (with one communication object pointer
+parameter). These chares and their entry methods have to be specified
+in the interface file.
+
+\subsubsection{Branched Chares}
+
+Branched chares\footnote{
+  These were called Branch Office Chares (BOC) in earlier version of Charm.
+} (or charegroups) are a special type of concurrent objects.
+Each branched chare is a collection of chares, with one representative on
+each processor. All the branches of a branched chare share a globally
+unique name (handle). An entire branched chare could be addressed using
+this global handle, and an individual branch of a branched chare can be
+addressed using the global handle, and a processor number. Branched chares
+are instances of C++ classes subclasses from a system-provided class called
+{\tt groupmember}. The runtime system has to be notified that these
+chares are semantically different, and therefore branched chares have 
+a different declaration in the interface specification file.
diff --git a/doc/charm++/quiesce.tex b/doc/charm++/quiesce.tex
new file mode 100644 (file)
index 0000000..739c461
--- /dev/null
@@ -0,0 +1,67 @@
+\subsection{Quiescence Detection}
+
+In \charmpp, \index{quiescence}quiescence is defined as the state in which no
+processor is executing an entry point, and no messages are awaiting processing.
+
+\charmpp\ provides two facilities for detecting quiescence: \kw{CkStartQd} and
+\kw{CkWaitQd}. \index{CkStartQd} \index{CkWaitQd}
+
+\kw{CkStartQd} registers with the system a callback that should be made the
+next time \index{quiescence}quiescence is detected.  \kw{CkStartQd} takes two
+parameters: an index corresponding to the entry function that is to be called,
+and a handle to the chare on which that entry function should be called.  The
+syntax of this call looks like this:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{CkStartQd}(\kw{int} {\it Index}, \kw{CkChareID} {\it chareID});
+\end{tabbing}
+
+To retrieve the corresponding index of a particular \index{entry method}entry
+method, you must use a static method contained within the
+\index{CProxy}\kw{CProxy} object corresponding to the \index{chare}chare
+containing that entry method.  The syntax of this call is as follows:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\kw{CProxy}\_\uw{ChareName}::\kw{ckIdx}\_\uw{EntryMethod}(\uw{Msg}
+*{\it Message});
+\end{tabbing}
+
+where {\it chareID} is the name of the chare identifier of the chare containing
+the desired entry method, \uw{EntryMethod} is the name of that entry method,
+and {\it Message} is a pointer to the kind of message that the desired entry
+method takes as a parameter. To make this look a little cleaner, we have
+provided a simple macro called \kw{EntryIndex}, which can be used in the place
+of this convoluted looking static method call.
+\kw{EntryIndex}\index{EntryIndex} takes as parameters the type of chare in
+which the entry method is located, the name of the entry method itself, and the
+type of message that the entry method takes as a parameter. For example:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{EntryIndex}(\uw{ChareName}, \uw{EntryName}, \uw{MsgName});
+\end{tabbing}
+
+Note that ChareName, EntryName, and MsgName are {\bf NOT} variables or
+constants. This is text that the preprocessor uses to fill in portions of the
+previously mentioned static method call.  Additionally, this macro method will
+not work with templated chares (refer to Section ~\ref{inheritance and
+templates} for details on templated chares).
+
+\index{CkWaitQd}\kw{CkWaitQd}, however, does not register a callback.  Rather,
+\kw{CkWaitQd} blocks and does not return until \index{quiescence}quiescence is
+detected.  It takes no parameters and returns no value.  A call to
+\kw{CkWaitQd} simply looks like this: 
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{CkWaitQd}();
+\end{tabbing}
+
+Keep in mind that \kw{CkWaitQd} should only be called from threaded
+\index{entry method}entry methods because a call to \kw{CkWaitQd} suspends the
+current thread of execution, and if it were called outside of a threaded entry
+method it would suspend the main thread of execution of the processor from
+which \kw{CkWaitQd} was called and the entire program would come to a grinding
+halt on that processor.
diff --git a/doc/charm++/readonly.tex b/doc/charm++/readonly.tex
new file mode 100644 (file)
index 0000000..95438e2
--- /dev/null
@@ -0,0 +1,69 @@
+\subsection{Read-only Variables, Messages and Arrays}
+
+Since \charmpp\ does not allow global variables, it provides a special
+mechanism for sharing data amongst all objects. {\it Read-only}
+variables, messages and arrays are used to share information that 
+is obtained only after the program begins execution and does not
+change after they are initialized in the {\tt main::main()} function. They
+can be accessed from any \index{chare}chare on any processor as ``global''
+variables. Large data structures containing pointers can be made
+available as read-only variables using read-only messages or
+read-only arrays. Read-only variables, messages and arrays can
+be used just like local variables for each processor, but the user has
+to allocate space for read-only messages using \kw{new} to create
+the message in the {\tt main} function of the \kw{mainchare}. 
+
+Read-only variables, messages, and arrays are declared by using the type
+modifier \index{readonly}\kw{readonly}, which is similar to \kw{const} in
+\CC. Read-only data is specified in the {\tt .ci} file (the interface
+file) as: 
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{readonly} \uw{Type} {\it ReadonlyVarName};
+\end{tabbing}
+
+The variable {\it ReadonlyVarName} is declared to be a read-only
+variable of type \uw{Type}. \uw{Type} must be a single token and not a
+type expression.
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{readonly} \uw{MessageType} *{\it ReadonlyMsgName};
+\end{tabbing}
+
+The variable {\it ReadonlyMsgName} is declared to be a read-only
+message of type \uw{MessageType}. Pointers are not allowed to be
+readonly variables unless they are pointers to message types. In this
+case, the message will be initialized on every processor.
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \kw{readonly} \uw{Type} {\it ReadonlyArrayName} [{\it arraysize}];
+\end{tabbing}
+
+The variable {\it ReadonlyArrayName} is declared to be a read-only
+array of type \uw{Type}. \uw{Type} must be a single token and not a
+type expression.
+
+Read-only variables, messages and arrays must be declared either as
+global or as public class static data, and these declarations have the
+usual form:
+
+\begin{tabbing}
+~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
+\> \uw{Type} {\it ReadonlyVarName}; \\
+\> \uw{MessageType} *{\it ReadonlyMsgName}; \\
+\> \uw{Type} {\it ReadonlyArrayName} [{\it arraysize}];
+\end{tabbing}
+
+Similar declarations preceded by \kw{extern} would appear in the {\tt
+.h} file. 
+
+{\it Note:}  The current \charmpp\ compiler cannot prevent
+assignments to read-only variables.  The user must make sure that no
+assignments occur in the program.
+
+
+
+
diff --git a/doc/charm++/related.tex b/doc/charm++/related.tex
new file mode 100644 (file)
index 0000000..24b8e8a
--- /dev/null
@@ -0,0 +1,15 @@
+\subsection{Related Publications}
+\label{publications}
+
+For starters, see the publications and reports as well
+as related manuals that can be found on the Parallel Programming
+Laboratory website: {\tt http://charm.cs.uiuc.edu/}. 
+
+Some \charmpp\ related papers:
+\cite{CharmppPPWCPP96},\cite{CharmppOOPSLA93}.  Papers on {\sc Converse}:
+\cite{ConverseRTSPP98}, \cite{InterOpIPPS96}. Some
+{\sc Charm} related papers that formed the early foundation for \charmpp:
+\cite{CharmSys1TPDS94}, \cite{CharmSys2TPDS94},
+\cite{CharmOverviewINTL93}.  Papers on Structured Dagger and Dagger: 
+\cite{DaggerSyncIPPS94}, \cite{StructDaggerEURO96}.  Projections
+papers: \cite{ProjectionsIPPS93}, \cite{Projections}.
\ No newline at end of file
diff --git a/doc/charm++/sdag.tex b/doc/charm++/sdag.tex
new file mode 100644 (file)
index 0000000..adaeebd
--- /dev/null
@@ -0,0 +1,273 @@
+\section{Structured Dagger}
+
+\newcommand{\sdag}{Structured Dagger}
+\newcommand{\charm}{Charm}
+%\newcommand{\charmpp}{Charm++}
+\newcommand{\wb}{when-block}
+\newcommand{\dagg}{Dagger}
+\newcommand{\md}{message-driven}
+\newcommand{\Md}{Message-driven}
+\newcommand{\MD}{Message-Driven}
+
+\charmpp\ is based on the \MD\ parallel programming paradigm.
+The \md\ programming style avoids the use of blocking receives and
+allows overlap of computation and communication by scheduling
+computations depending on availability of data.  This programing style
+enables \charmpp\ programs to
+tolerate communication latencies adaptively. Threads suffer from loss of
+performance due to context-switching overheads and limited scalability
+due to large and unpredictable stack memory requirements, when used 
+in a data-driven manner to
+coordinate a sequence of remotely triggered actions.
+
+The need to sequence remotely triggered actions
+arises in many situations. Let us consider an example:
+
+\begin{figure}
+\begin{center}
+\frame{
+\begin{minipage}[t]{3in}
+{\small
+{\tt
+\begin{tabbing}
+xx\=xx\=xx\=xx\=xx\=xx\=xx\kill
+\>      class compute\_object : public {\bf Chare} \{ \\
+\>      private:\\
+\>\>      int         count;\\
+\>\>      Patch       *first, *second;\\
+\>      public:\\
+\>\>      compute\_object(MSG *msg) \{\\
+\>\>  \>    count = 2; MyChareID(\&chareid); \\
+\>\>  \>    PatchManager->Get(msg->first\_index, recv\_first, \&thishandle,NOWAIT);\\
+\>\>  \>    PatchManager->Get(msg->second\_index, recv\_second, \&thishandle,NOWAIT);\\
+\>\>      \}\\
+\>\>      void recv\_first(PATCH\_MSG *msg) \{ \\
+\>\>  \>     first = msg->patch; \\
+\>\>  \>     filter(first); \\
+\>\>  \>     if (--count == 0 ) computeInteractions(first,second);\\
+\>\>      \} \\
+\>\>      void recv\_second(PATCH\_MSG *msg)\{\\
+\>\>  \>     second = msg->patch; \\
+\>\>  \>     filter(second); \\
+\>\>  \>     if (--count == 0) computeInteractions(first,second);\\
+\>\>      \} \\
+\>     \}
+\end{tabbing}
+}
+}
+\end{minipage}
+}
+\end{center}
+\caption{Compute Object in a Molecular Dynamics Application}
+\label{figchareexample}
+\end{figure}
+
+
+Consider an algorithm for computing cutoff-based pairwise interactions
+between atoms in a molecular dynamics application, where interaction
+between atoms is considered only when they are within some cutoff
+distance of each other.  This algorithm is based on a combination of
+task and spatial decompositions of the molecular system. The bounding
+box for the molecule is divided into a number of cubes ({\em Patches})
+each containing some number of atoms.  Since each patch contains a
+different number of atoms and these atoms migrate between patches as
+simulation progresses, a dynamic load balancing scheme is used. In
+this scheme, the task of computing the pairwise interactions between
+atoms of all pairs of patches is divided among a number of {\em
+Compute Objects}. These compute objects are assigned at runtime to
+different processors. The initialization message for each compute
+object contains the indices of the patches. The patches themselves are
+distributed across processors. Mapping information of patches to
+processors is maintained by a replicated object called {\em
+PatchManager}.  Figure~\ref{figchareexample} illustrates the \charmpp\
+implementation of the compute object. Each compute object requests
+information about both patches assigned to it from the
+PatchManager. PatchManager then contacts the appropriate processors
+and delivers the patch information to the requesting compute
+object. The compute object, after receiving information about each
+patch, determines which atoms in a patch do not interact with atoms in
+another patch since they are separated by more than the cut-off
+distance. This is done in method {\tt filter}.  Filtering could be
+done after both patches arrive. However, in order to increase
+processor utilization, we do it immediately after any patch
+arrives. Since the patches can arrive at the requesting compute object
+in any order, the compute object has to buffer the received patches,
+and maintain state information using counters or flags.  This example
+has been chosen for simplicity in order to demonstrate the necessity
+of counters and buffers.  In general, a parallel algorithm may have
+more interactions leading to the use of many counters, flags, and
+message buffers, which complicates program development significantly.
+
+Threads are typically used to perform the abovementioned sequencing.
+Lets us code our previous example using threads.
+
+\begin{figure}
+\begin{center}
+\frame{
+\begin{minipage}[t]{3in}
+{\small
+{\tt
+\begin{tabbing}
+xx\=xx\=xx\=xx\=xx\=xx\=xx\kill
+\>void compute\_thread(int first\_index, int second\_index)\\
+\>\{\\
+\>\>getPatch(first\_index);\\
+\>\>getPatch(second\_index);\\
+\>\>threadId[0] = createThread(recvFirst);\\
+\>\>threadId[1] = createThread(recvSecond);\\
+\>\>threadJoin(2, threadId);\\
+\>\>computeInteractions(first, second);\\
+\>\}\\
+\>void recvFirst(void)\\
+\>\{\\
+\>\>recv(first, sizeof(Patch), ANY\_PE, FIRST\_TAG);\\
+\>\>filter(first);\\
+\>\}\\
+\>void recvSecond(void)\\
+\>\{\\
+\>\>recv(second, sizeof(Patch), ANY\_PE, SECOND\_TAG);\\
+\>\>filter(second);\\
+\>\}\\
+\end{tabbing}
+}
+}
+\end{minipage}
+}
+\end{center}
+\caption{Compute Thread in a Molecular Dynamics Application}
+\label{figthreadexample}
+\end{figure}
+
+
+Contrast the compute chare-object example in
+figure~\ref{figchareexample} with a thread-based implementation of the
+same scheme in figure~\ref{figthreadexample}. Functions {\tt
+getFirst}, and {\tt getSecond} send messages asynchronously to the
+PatchManager, requesting that the specified patches be sent to them,
+and return immediately. Since these messages with patches could arrive
+in any order, two threads, {\tt recvFirst} and {\tt recvSecond}, are
+created. These threads block, waiting for messages to arrive. After
+each message arrives, each thread performs the filtering
+operation. The main thread waits for these two threads to complete,
+and then computes the pairwise interactions. Though the programming
+complexity of buffering the messages and maintaining the counters has
+been eliminated in this implementation, considerable overhead in the
+form of thread creation, and synchronization in the form of {\em join}
+has been added. Let us now code the same example in \sdag. It reduces the
+parallel programming complexity without adding any significant
+overhead.
+
+\begin{figure}
+\begin{center}
+\frame{
+\begin{minipage}[t]{3in}
+{\small
+{\tt
+\begin{tabbing}
+xx\=xx\=xx\=xx\=xx\=xx\kill
+\>{\bf class} compute\_object \\
+\>\>{\bf sdagentry} compute\_object(MSG *msg)\{ \\
+\>\>\>{\bf atomic} \{\\
+\>\>\>\> PatchManager->Get(msg->first\_index,\dots); \\
+\>\>\>\> PatchManager->Get(msg->second\_index,\dots); \\
+\>\>\>\} \\
+\>\>\>{\bf overlap} \{\\
+\>\>\>\>{\bf when} recv\_first(Patch *first) {\bf atomic} \{ filter(first); \}\\
+\>\>\>\>{\bf when} recv\_second(Patch *second) {\bf atomic} \{ filter(second); \}\\
+\>\>\>\}\\
+\>\>\>{\bf atomic} \{ computeInteractions(first, second); \}\\
+\>\>\}\\
+\>\}
+\end{tabbing}
+}
+}
+\end{minipage}
+}
+\end{center}
+\caption{\sdag\ Implementation of the Compute Object}
+\label{figsdagexample}
+\end{figure}
+
+\sdag\ \cite{StructDaggerEURO96}  is a coordination language built on top of
+\charmpp\ that supports the sequencing mentioned above,
+while overcoming limitations of thread-based languages, and
+facilitating a clear expression of flow of control within the object
+without losing the performance benefits of adaptive message-driven
+execution.  In other words, \sdag\ is a structured notation for
+specifying intra-process control dependences in message-driven
+programs. It combines the efficiency of message-driven execution with
+the explicitness of control specification. \sdag\ allows easy
+expression of dependences among messages and computations and also
+among computations within the same object using when-blocks and
+various structured constructs.  \sdag\ is adequate for expressing
+control-dependencies that form a series-parallel control-flow graph.
+\sdag\ has been developed on top of \charmpp\. \sdag\ allows
+\charmpp\ entry methods (in chares, groups or arrays) to specify
+code (a when-block body) to be executed upon occurrence of certain events. 
+These events (or guards of a when-block) are entry methods of the object that
+can be invoked remotely. While writing a \sdag\ program, one has to declare these
+entries in \charmpp\ interface file. The implementation of the
+entry methods that contain the when-block is written using the \sdag\
+language. Grammar of \sdag\ is given in the EBNF form below.
+
+\subsection{Grammar}
+
+\subsubsection{Tokens}
+
+\begin{verbatim}
+  <ident> = Valid C++ identifier 
+  <int-expr> = Valid C++ integer expression 
+  <c++-code> = Valid C++ code 
+\end{verbatim}
+
+\subsubsection{Grammar in EBNF Form}
+
+\begin{verbatim}
+<sdag> := <class-decl> <sdagentry>+ 
+
+<class-decl> := "class" <ident> 
+
+<sdagentry> := "sdagentry" <ident> "(" <ident> "*" <ident> ")" <body> 
+
+<body> := <stmt> 
+        | "{" <stmt>+ "}" 
+
+<stmt> := <overlap-stmt> 
+        | <when-stmt> 
+        | <atomic-stmt> 
+        | <if-stmt> 
+        | <while-stmt> 
+        | <for-stmt> 
+        | <forall-stmt> 
+
+<overlap-stmt> := "overlap" <body> 
+
+<atomic-stmt> := "atomic" "{" <c++-code> "}" 
+
+<if-stmt> := "if" "(" <int-expr> ")" <body> [<else-stmt>] 
+
+<else-stmt> := "else" <body> 
+
+<while-stmt> := "while" "(" <int-expr> ")" <body> 
+
+<for-stmt> := "for" "(" <c++-code> ";" <int-expr> ";" <c++-code> ")" <body> 
+
+<forall-stmt> := "forall" "[" <ident> "]" "(" <range-stride> ")" <body> 
+
+<range-stride> := <int-expr> ":" <int-expr> "," <int-expr> 
+
+<when-stmt> := "when" <entry-list>  <body> 
+
+<entry-list> := <entry> 
+              | <entry> [ "," <entry-list> ] 
+
+<entry> := <ident> [ "[" <int-expr> "]" ] "(" <ident> "*" <ident> ")" 
+  
+\end{verbatim}
+
+
+For more details regarding \sdag, look at the examples located in
+{\tt pgms/sdag} directory in the \charmpp\ distribution.
+
+
+
diff --git a/doc/charm++/seqobjs.tex b/doc/charm++/seqobjs.tex
new file mode 100644 (file)
index 0000000..b04a79f
--- /dev/null
@@ -0,0 +1,6 @@
+\subsection{Sequential Objects}
+\index{sequential objects} 
+
+These are the same as C++ classes and functions.  All C++ features can
+be used.  However, care needs to be taken when sequential objects
+interact with \charmpp\ objects.
diff --git a/doc/charm++/syntaxchange.tex b/doc/charm++/syntaxchange.tex
new file mode 100644 (file)
index 0000000..165f053
--- /dev/null
@@ -0,0 +1,98 @@
+\section{Syntax Changes from \charmpp\ 4.9}
+
+The following changes are required to make older \charmpp\ 4.9
+programs run with the new translator and runtime system in
+\charmpp\ 5.0.
+
+\begin{itemize}
+
+\item Replace all references to {\tt *.top.h} and {\tt *.bot.h} to
+{\tt *.decl.h} and {\tt *.def.h} respectively. This should be done in
+Makefile, and everywhere these two types of files are included.
+
+\item Change all X.ci files to include a top-level enclosure of module X {...}.
+
+\item Change \kw{chare} \uw{main} to \kw{mainchare} \uw{main}.
+
+\item Replace \kw{chare\_object} by \kw{Chare}.
+
+\item Replace \kw{groupmember} by \kw{Group}.
+
+\item Replace \kw{comm\_object} by \uw{CMessage\_<msgName>} in all
+message declarations in {\tt *.h} files. 
+
+\item Remove all \kw{operator new} methods of messages.
+
+\item Remove \kw{MsgIndex(..)} parameter to \kw{new} for message allocation.
+
+\item Remove all the empty messages (used only for triggering
+computations.) from {\tt *.h}, {\tt *.ci}, {\tt *.C} files. All the
+entry methods that take these empty messages as parameters should be
+made methods with \kw{void} parameter. This should be done in all {\tt
+*.ci}, {\tt *.h}, and {\tt *.C} files.  In these methods, there may be
+a {\tt delete msg}. Remove that. 
+
+\item Check for \kw{mainhandle} in the source. If it is there, declare
+it as a \kw{readonly} variable in {\tt .ci} file, and initialize it in
+the \kw{mainchare}'s constructor, so that it is available to all the
+processors during the run.
+
+\item All the \kw{packmessage} declarations in {\tt *.ci} files should
+be changed to \kw{message [packed]}. 
+
+\item All \kw{CPrintf}, \kw{CScanf}, and \kw{CError} should be changed
+to \kw{CkPrintf}, \kw{CkScanf}, and \kw{CkError}. 
+
+\item All \kw{CharmExit} should be changed to \kw{CkExit}.
+
+\item Replace \kw{CMyPe} by \kw{CkMyPe}. Replace \kw{CNumPes} by \kw{CkNumPes}.
+
+\item Change \kw{ChareIDType} to \kw{CkChareID}.
+
+\item Change signature of \uw{M::pack} and \uw{M::unpack} for all
+messages \uw{M} in {\tt *.h}, {\tt *.C} to\\
+\verb+static void *pack(M* msg)+\\
+and\\
+\verb+static M* unpack(void *buf)+\\
+and change the code
+accordingly. This is a significant change because {\tt pack} and {\tt unpack}
+used to be instance methods, and now they are class static
+methods.  Avenues of optimizations open with this change, but one need
+not explore those in the interest of time immediately. Further, one
+should make sure that the performance of the new scheme is at least as
+good as the old one. 
+
+\item Replace all \kw{new\_group} by \uw{CProxy\_<grpName>::ckNew}.
+
+\item Replace \kw{new\_chare2} by proxy creation.
+
+\item Replace \kw{CSendMsg} by temporary proxy creation based on
+ChareID and invoking appropriate method on it. One optimization is to
+create a proxy immediately after a ChareID is received, and reusing it
+everytime.
+
+\item Similarly replace \kw{CSendMsgBranch} by temporary proxy
+creation based on the groupID, and invoking appropriate method on it,
+with processor number as the second parameter. Once again, there is an
+opportunity for optimization here. 
+
+\item Similarly replace \kw{CBroadcastMsgBranch} by temporary proxy
+creation based on the groupID, and invoking appropriate method on it,
+without any second parameter. Once again, there is an opportunity for
+optimization here. 
+
+\item Replace \kw{CStartQuiescence} by \kw{CkStartQD}.
+
+\item Replace \kw{GetEntryPtr} by appropriate static method
+(\kw{ckIdx\_*}) calls. 
+
+\item Replace \kw{CLocalBranch} macros by \kw{ckLocalBranch} instance
+method on temporarily created proxy. 
+
+\item Change \kw{CPriorityPtr} to \kw{CkPriorityPtr}, also cast it
+explicitly to {\tt (int *)}. 
+
+\item Replace \kw{QuiescenceMessage} by \kw{CkQDMsg}. Remove all
+extern declarations of \kw{CkQDMsg} from {\tt *.ci} files.
+
+\end{itemize}
diff --git a/doc/charm++/tools.tex b/doc/charm++/tools.tex
new file mode 100644 (file)
index 0000000..6fec5fe
--- /dev/null
@@ -0,0 +1,266 @@
+\subsection{Associated Tools and Libraries}
+
+Several tools and libraries are provided for \charmpp. {\bf
+Projections} is an automatic performance analysis tool which provides
+the user with information about the parallel behavior of \charmpp\ programs. The purpose of implementing \charmpp standard
+libraries is to reduce the time needed to develop parallel
+applications with the help of a set of efficient and re-usable modules.
+
+\subsubsection{Projections}
+{\bf Projections} \cite{ProjectionsIPPS93}, \cite{Projections} is a
+performance visualization and feedback tool. The system has a much
+more refined understanding of user computation than is possible in
+traditional tools.
+
+Projections displays information about the request for creation and
+the actual creation of tasks in \charmpp\ programs. Projections also
+provides the function of post-mortem clock
+synchronization. Additionally, it can also automatically partition
+the execution of the running program into logically separate units,
+and automatically analyzes each individual partition. 
+
+Future versions will be able to provide recommendations/suggestions
+for improving performance as well.
+
+\subsubsection{TeMPO}
+
+{\bf TeMPO} (Threaded Message Passing Objects) provides a simple way
+to communicate between threaded methods of objects. Using TeMPO,
+chares, groups, and arrays can have threads associated with
+them. Any \charmpp\ object can send a tagged message to a TeMPO Object,
+and a threaded method in a TeMPO Object can block on a specific tagged
+message.
+
+In order to use TeMPO functionalities, chares, groups, and arrays need
+to inherit from TeMPO objects called \kw{TempoChare}, \kw{TempoGroup}\footnote{
+Currently, a nodegroup variety of TeMPO object does not exist, thoug it will
+be added in future.},
+and \kw{TempoArray} respectively. This inheritance also needs to be
+specified in the \charmpp\ interface file. Thus, a chare C in module M
+that needs to receive a tagged message directed to it in entry E, 
+needs to inherit from \kw{TempoChare} as shown below:
+
+\begin{verbatim}
+// file.ci
+module M {
+ ...
+ chare C : TempoChare {
+   entry C(void);
+   entry [threaded] void E(Msg *); // note use of threaded
+ };
+ ...
+}
+
+// file.h
+#include "file.decl.h"
+...
+class C : public TempoChare { // TempoChare inherits from Chare already
+ public:
+  C(void);
+  E(Msg *);
+};
+...
+\end{verbatim}
+
+The code for entry method \uw{E} can contain a call to \kw{ckTempoRecv}
+to block for a tagged message. Any ordinary chare can send a tagged
+message to a TeMPO object using \kw{ckTempoSend} static method of 
+\kw{TempoChare}.
+
+\kw{TempoGroup} and \kw{TempoArray} provide additional static methods to
+send tagged messages to individual elements, as well as broadcast. In
+addition, \kw{TempoArray} provides methods to perform ``reduction''
+over all the elements of an array. Currently supported reduction operations
+are max, min, sum, and product over datatypes float, int, and double.
+The signatures of these methods are given below:
+
+\begin{verbatim}
+class TempoChare : public Chare, public ... {
+  void ckTempoRecv(int tag, void *buffer, int buflen);
+  void ckTempoRecv(int tag1, int tag2, void *buffer, int buflen);
+  static void ckTempoSend(int tag1, int tag2, void *buffer,int buflen,
+                          CkChareID cid);
+  static void ckTempoSend(int tag, void *buffer,int buflen, CkChareID cid);
+  int ckTempoProbe(int tag1, int tag2);
+  int ckTempoProbe(int tag);
+};
+
+// TempoGroup includes all the TempoChare methods
+
+class TempoGroup : public Group, public ... {
+  static void ckTempoBcast(int tag, void *buffer, int buflen, CkGroupID grpid);
+  static void ckTempoSendBranch(int tag1, int tag2, void *buffer, int buflen,
+                                CkGroupID grpid, int processor);
+  static void ckTempoSendBranch(int tag, void *buffer, int buflen,
+                                CkGroupID grpid, int processor);
+  void ckTempoBcast(int sender, int tag, void *buffer, int buflen);
+  void ckTempoSendBranch(int tag1, int tag2, void *buffer, int buflen,
+                         int processor);
+  void ckTempoSendBranch(int tag, void *buffer, int buflen, int processor);
+};
+
+// TempoArray includes all the TempoChare methods
+
+class TempoArray : public ArrayElement, public Tempo
+{
+  static void ckTempoSendElem(int tag1, int tag2, void *buffer, int buflen,
+                              CkArrayID aid, int idx);
+  static void ckTempoSendElem(int tag, void *buffer, int buflen,
+                              CkArrayID aid, int idx);
+  void ckTempoSendElem(int tag1, int tag2, void *buffer, int buflen, int idx);
+  void ckTempoSendElem(int tag, void *buffer, int buflen, int idx);
+  void ckTempoBarrier(void);
+  void ckTempoBcast(int sender, int tag, void *buffer, int buflen);
+  void ckTempoReduce(int root, int op, void *inbuf, void *outbuf, int count,
+                     int type);
+  void ckTempoAllReduce(int op,void *inbuf,void *outbuf,int count,int type);
+};
+\end{verbatim}
+
+All the {\tt ckSend*} methods have versions that send messages with one tag or
+with two tags. A wild card tag (\kw{TEMPO\_ANY} may be in specified in \kw{ckTempoRecv}
+that matches with any tag. All the tags must range between 0 and 1024. All the other
+tags have other uses in the system. Reduction operations are indicated by integer constants.
+They are: \kw{TEMPO\_MAX}, \kw{TEMPO\_MIN}, \kw{TEMPO\_SUM}, and \kw{TEMPO\_PROD}.
+Reduction data types can be specified using integer constants: \kw{TEMPO\_FLOAT},
+\kw{TEMPO\_INT}, and \kw{TEMPO\_DOUBLE}. The \uw{root} parameter in \kw{ckTempoReduce},
+and the \uw{sender} parameter in \kw{ckTempoBcast} indicate whether the calling element
+is the root of the collective operation or not. In case of a reduction,
+the root element is returned the result of the reduction operation in
+\uw{outbuf}\footnote{\uw{outbuf} and \uw{inbuf} can be the same.} In case of a
+broadcast, \uw{buffer} on the sender contains the message to be sent to other elements.
+For each of the send methods, the specified message buffer could be reused once
+the method returns.
+
+All the TeMPO include files are automatically includes from {\tt charm++.h}.
+There is no need to include any other file to use TeMPO.
+
+\subsubsection{Communication}
+Communication optimizations tend to be specific to a particular
+architecture or an application. To improve portability and to reduce the
+cost of developing parallel applications a mechanism to integrate these
+different optimizations should exist. Moreover, it should be possible to
+automatically adapt the strategy to the situation at hand. The
+communication library integrates the different strategies to perform
+each-to-many multicast, including tree-based multicast, grid -based
+multicast and hypercube-based (dimensional exchange) schemes. The
+framework provided is flexible enough to absorb new strategies and
+communication patterns. It also provides the capability to do dynamic
+switching of strategies. This helps the library to adapt itself to the
+existing environment.
+
+\subsubsection{Barrier}
+We needed a way to synchronise a subset of tasks in \charmpp\
+programs. Quiescence detection is one way this can be done, if we want
+to synchronize {\bf all} tasks, but barriers provide a more flexible
+option with less overhead. 
+
+To make use of barriers, the user initializes a {\sl barrier group} in
+the main function. A virtual binary tree structure is imposed on the
+PEs, with PE 0 at the root.  PEs perform computations and then execute
+{\tt atBarrier} when they want to synchronize.  {\tt atBarrier} takes
+a single parameter of type {\tt FP *}.  The user must declare and
+initialize some variable {\it fnptr} as follows:
+
+\begin{verbatim}
+  FP *fnptr = new FP;
+
+  fnptr->fp = theFn;
+\end{verbatim}
+
+The variable {\it theFn} above is the void function to be executed when all
+PEs have synchronized.
+
+The barrier keeps track of child PEs, and when a given PE has heard
+from all its children, it then notifies the parent.  When the root
+hears from both children, all PEs are accounted for, and the
+respective void function is executed on each PE. 
+
+What follows is a very simple test program illustrating the usage of a
+barrier.
+
+{\tt test.ci}:
+
+\begin{verbatim}
+mainmodule Test {
+  extern module Barrier;
+  readonly CkChareID mainhandle;
+  readonly int barrierGroup;
+  
+  mainchare main {
+    entry main();
+    entry void Quiescence1(void);
+  };
+  
+  group busy {
+    entry busy(void);
+  };
+};
+\end{verbatim}
+
+{\tt test.h}:
+
+\begin{verbatim}
+#include "Test.decl.h"
+int barrierGroup;
+CkChareID mainhandle;
+
+class main : public Chare {
+public:
+  main(CkArgMsg *m);
+  void Quiescence1(void);
+};
+
+class busy : public Group {
+public:
+  busy(void);
+}
+\end{verbatim}
+
+{\tt test.C}:
+
+\begin{verbatim}
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+
+#include "charm++.h"
+
+#include "test.h"
+#include "Test.def.h"
+
+#include "barrier.h"
+
+main::main(CkArgMsg *m)
+{
+  barrierGroup = barrierInit();
+  CProxy_busy::ckNew();
+  CkStartQD(CProxy_main::ckIdx_Quiescence1(), &mainhandle);
+}
+
+void main::Quiescence1() 
+{ 
+  CkPrintf("All done... Exiting.\n");
+  CkExit();
+}
+
+void theFn();
+
+busy::busy()
+{
+  int i, j=0;
+  FP *fnptr = new FP;
+
+  for (i=0; i<(CkMyPe()+1)*1000000; i++)
+    j = j + i;
+  CkPrintf("[%d] going to barrier with j=%d\n", CkMyPe(), j);
+  fnptr->fp = theFn;
+  CProxy_barrier(barrierGroup).ckLocalBranch()->atBarrier(fnptr);
+}
+
+void theFn()
+{
+  CkPrintf("[%d] fnptr executing!\n", CkMyPe());
+}
+\end{verbatim}
+