doc: lots more chapterize for charm manual
authorRamprasad Venkataraman <ramv@illinois.edu>
Wed, 25 Jul 2012 19:06:51 +0000 (14:06 -0500)
committerRamprasad Venkataraman <ramv@illinois.edu>
Wed, 25 Jul 2012 19:23:51 +0000 (14:23 -0500)
doc/charm++/Makefile
doc/charm++/credits.tex
doc/charm++/further.tex
doc/charm++/futures.tex
doc/charm++/history.tex [new file with mode: 0644]
doc/charm++/manual.tex
doc/charm++/quiesce.tex

index 51f1ea4da2f108d514a1defba60f9decbb587f90..9284be7ba3a03b2c84261ee8624c53759fff6f74 100644 (file)
@@ -5,7 +5,7 @@ TEX=$(FILE).tex arrays.tex callbacks.tex chares.tex commlib.tex delegation.tex \
        helloworld.tex utilities.tex loadb.tex advancedlb.tex futures.tex \
        marshalling.tex messages.tex modules.tex nodegroups.tex othercalls.tex \
        overview.tex pup.tex advancedpup.tex quiesce.tex readonly.tex reductions.tex sdag.tex \
-       python.tex alltoall.tex
+       python.tex alltoall.tex history.tex
 DEST=charm++
 LATEX2HTML=$(L2H) -split 5
 
index 1eee56c92ea639037b385e701471f04ed5b2e245..4099598284c6d82fafc491a2939fbc2990a69e0e 100644 (file)
@@ -1,46 +1,3 @@
-\section{History}
-
-The {\sc Charm} software was developed as a group effort of the Parallel
-Programming Laboratory at the University of Illinois at Urbana-Champaign.
-Researchers at the Parallel Programming Laboratory keep \charmpp\ updated for
-the new machines, new programming paradigms, and for supporting and simplifying
-development of emerging applications for parallel processing.  The earliest
-prototype, Chare Kernel(1.0), was developed in the late eighties. It consisted
-only of basic remote method invocation constructs available as a library.  The
-second prototype, Chare Kernel(2.0), a complete re-write with major design
-changes.  This included C language extensions to denote Chares, messages and
-asynchronous remote method invocation.  {\sc Charm}(3.0) improved on this
-syntax, and contained important features such as information sharing
-abstractions, and chare groups (called Branch Office Chares).  {\sc Charm}(4.0)
-included \charmpp\ and was released in fall 1993.  \charmpp\ in its initial
-version consisted of syntactic changes to \CC\ and employed a special
-translator that parsed the entire \CC\ code while translating the syntactic
-extensions.  {\sc Charm}(4.5)  had a major change that resulted from a
-significant shift in the research agenda of the Parallel Programming
-Laboratory. The message-driven runtime system code of the \charmpp\ was
-separated from the actual language implementation, resulting in an
-interoperable parallel runtime system called {\sc
-Converse}. The \charmpp\ runtime system was
-retargetted on top of {\sc Converse}, and popular programming paradigms such as
-MPI and PVM were also implemented on {\sc Converse}. This allowed
-interoperability between these paradigms and \charmpp. This release also
-eliminated the full-fledged \charmpp\ translator by replacing syntactic
-extensions to \CC\ with \CC\ macros, and instead contained a small language and
-a translator for describing the interfaces of \charmpp\ entities to the runtime
-system.  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}.  In early 1999, the runtime system of
-\charmpp\ 
-%was formally named the Charm Kernel, and 
-was rewritten in \CC.
-Several new features were added. The interface language underwent significant
-changes, and the macros that replaced the syntactic extensions in original
-\charmpp, were replaced by natural \CC\ constructs. Late 1999, and early
-2000 reflected several additions to \charmpp{}, when a load balancing
-framework and migratable objects were added to \charmpp{}.
-
-\section {Acknowledgements}
-
 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
index 7f720d5732825f3ad7dd14813f5f34ea3e98e018..9f92b261184ec191f14b59ede23076b942d489df 100644 (file)
@@ -1,7 +1,4 @@
-\section{Further Information}
-
-\subsection{Related Publications}
-
+\section{Related Publications}
 \label{publications}
 
 For starters, see the publications, reports, and manuals 
@@ -17,7 +14,7 @@ libraries is to reduce the time needed to develop parallel
 applications with the help of a set of efficient and re-usable modules.
 Most of the libraries have been described in a separate manual.
 
-\subsubsection{\projections}
+\subsection{\projections}
 
 \projections{} is a performance visualization and feedback tool. The system has
 a much more refined understanding of user computation than is possible in
@@ -32,8 +29,7 @@ separate units, and automatically analyzes each individual partition.
 Future versions will be able to provide recommendations/suggestions for
 improving performance as well.
 
-\subsection{Contacts}
-
+\section{Contacts}
 \label{Distribution}
 
 While we can promise neither bug-free software nor immediate solutions   
@@ -58,3 +54,4 @@ please send electronic mail to \texttt{kale@cs.uiuc.edu} or postal mail to:
    201 N. Goodwin Ave.
    Urbana, IL 61801 
 \end{alltt}
+
index 0e131a81d03fb4addace5ea211ee1307199f8a9a..ea744eb6b5edd2cfc8293c7018853b11e921c2a6 100644 (file)
@@ -1,5 +1,4 @@
-\subsection{Futures}
-
+\section{Futures}
 \label{futures}
 
 Similar to Multilisp and other functional programming languages, \charmpp\ provides the abstraction of {\em futures}. In simple terms, a {\em future} is a contract with the runtime system to evaluate an expression asynchronously with the calling program. This mechanism promotes the evaluation of expressions in parallel as several threads concurrently evaluate the futures created by a program.
diff --git a/doc/charm++/history.tex b/doc/charm++/history.tex
new file mode 100644 (file)
index 0000000..8e1158d
--- /dev/null
@@ -0,0 +1,39 @@
+The {\sc Charm} software was developed as a group effort of the Parallel
+Programming Laboratory at the University of Illinois at Urbana-Champaign.
+Researchers at the Parallel Programming Laboratory keep \charmpp\ updated for
+the new machines, new programming paradigms, and for supporting and simplifying
+development of emerging applications for parallel processing.  The earliest
+prototype, Chare Kernel(1.0), was developed in the late eighties. It consisted
+only of basic remote method invocation constructs available as a library.  The
+second prototype, Chare Kernel(2.0), a complete re-write with major design
+changes.  This included C language extensions to denote Chares, messages and
+asynchronous remote method invocation.  {\sc Charm}(3.0) improved on this
+syntax, and contained important features such as information sharing
+abstractions, and chare groups (called Branch Office Chares).  {\sc Charm}(4.0)
+included \charmpp\ and was released in fall 1993.  \charmpp\ in its initial
+version consisted of syntactic changes to \CC\ and employed a special
+translator that parsed the entire \CC\ code while translating the syntactic
+extensions.  {\sc Charm}(4.5)  had a major change that resulted from a
+significant shift in the research agenda of the Parallel Programming
+Laboratory. The message-driven runtime system code of the \charmpp\ was
+separated from the actual language implementation, resulting in an
+interoperable parallel runtime system called {\sc
+Converse}. The \charmpp\ runtime system was
+retargetted on top of {\sc Converse}, and popular programming paradigms such as
+MPI and PVM were also implemented on {\sc Converse}. This allowed
+interoperability between these paradigms and \charmpp. This release also
+eliminated the full-fledged \charmpp\ translator by replacing syntactic
+extensions to \CC\ with \CC\ macros, and instead contained a small language and
+a translator for describing the interfaces of \charmpp\ entities to the runtime
+system.  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}.  In early 1999, the runtime system of
+\charmpp\ 
+%was formally named the Charm Kernel, and 
+was rewritten in \CC.
+Several new features were added. The interface language underwent significant
+changes, and the macros that replaced the syntactic extensions in original
+\charmpp, were replaced by natural \CC\ constructs. Late 1999, and early
+2000 reflected several additions to \charmpp{}, when a load balancing
+framework and migratable objects were added to \charmpp{}.
+
index d1a762976c33f5172753d0086c5de87d7143cc36..211f596b79be9bc46fa7fddf7d57d42c68b9d24e 100644 (file)
@@ -56,6 +56,7 @@ node, PE, ranks?, smp-mode and non-smp mode terminology. etc.
 
 \chapter{Startup Order}
 
+
 \part{Advanced Usage}
 
 \chapter{Optimizing Entry Method Invocation}
@@ -63,13 +64,15 @@ node, PE, ranks?, smp-mode and non-smp mode terminology. etc.
   \input{messages}
   \input{order.tex}
 
-\chapter{Threads, Futures, sync, barriers, quiesce, completion etc ...}
-  \input{futures}
-  \input{quiesce}
-
 \chapter{Callbacks}
   \input{callbacks}
 
+\chapter{Waiting on Completion}
+  \section{Asynchronous Barriers}
+  \section{Threaded Entry Methods}
+  \input{futures}
+  \input{quiesce}
+
 \chapter{More Chare Array Features}
 \label{advanced arrays}
   \input{advancedarrays}
@@ -81,6 +84,8 @@ node, PE, ranks?, smp-mode and non-smp mode terminology. etc.
 \chapter{Reductions}
   \input{reductions}
   \input{alltoall}
+
+\chapter{Serialization}
   \input{advancedpup}
 
 \chapter{More Load Balancing}
@@ -92,7 +97,6 @@ node, PE, ranks?, smp-mode and non-smp mode terminology. etc.
   \input{checkpoint}
 
   \input{othercalls}    
-  \input{delegation}    
 %  \input{commlib}
 
 
@@ -107,20 +111,28 @@ node, PE, ranks?, smp-mode and non-smp mode terminology. etc.
 \label{sec:controlpoint}
   \input{controlpoints}
 
+\chapter{Writing Libraries for Custom Messaging}
+  \input{delegation}
+
 % TO BE MOVED TO ITS OWN MANUAL
 %\input{msa.tex}
 
+
 \part{Appendix}
 \appendix
 
-
 % TO BE MOVED TO ITS OWN MANUAL
 %\input{quickbigsim}
 
-\input{further}
+\chapter{Further Information}
+  \input{further}
 
-\input{index}
+\chapter{History}
+  \input{history}
+
+\chapter {Acknowledgements}
+  \input{credits}
 
-\input{credits}
+\input{index}
 
 \end{document}
index 9e8c8e38c307bff7c69acc6b182a9a7ff72d7f84..ffa6f447e1d0056cc4f4fbe7c8f9d85a70e4e7eb 100644 (file)
@@ -1,68 +1,4 @@
-\subsection{Quiescence Detection}
-
-\label{sec:qd}
-
-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}.
-
-\kw{CkStartQD} registers with the system a callback that should be made the
-next time \index{quiescence}quiescence is detected.  \kw{CkStartQD} has two
-variants which expect the following arguments: 
-\begin{enumerate}
-\item 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{alltt}
- CkStartQD(int Index,const CkChareID* chareID);
-\end{alltt}
-
-To retrieve the corresponding index of a particular \index{entry method}entry
-method, you must use a static method contained within the \uw{CkIndex} object
-corresponding to the \index{chare}chare containing that entry method.  The
-syntax of this call is as follows:
-
-\begin{alltt}
-\kw{myIdx}=CkIndex_\uw{ChareClass}::\uw{EntryMethod}(\uw{parameters});
-\end{alltt}
-
-where \uw{ChareClass} is the C++ class of the chare containing
-the desired entry method, \uw{EntryMethod} is the name of that entry method,
-and \uw{parameters} are the parameters taken by the method.
-These parameters are only used to resolve the proper \uw{EntryMethod};
-they are otherwise ignored.
-
-\item 
-A \uw{CkCallback} object. The syntax of this call looks like:
-\begin{alltt}
-  CkStartQD(const CkCallback& cb);
-\end{alltt}
-
-Upon quiescence detection, specified callback is called with no parameters.
-
-\end{enumerate}
-
-
-\kw{CkWaitQD}, by contrast, 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{alltt}
-  CkWaitQD();
-\end{alltt}
-
-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.
-
-\subsubsection{Completion Detection}
+\section{Completion Detection}
 
 Completion detection is a method for automatically detecting
 completion of a distributed process within an application. It is a
@@ -153,3 +89,67 @@ At some point, when everyone is consuming elements, completion will be
 reached. The system will detect that state and will trigger the \verb|finish|
 callback. At that point, \verb|start_detection| can be called again to restart
 the process.
+
+\section{Quiescence Detection}
+\label{sec:qd}
+
+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}.
+
+\kw{CkStartQD} registers with the system a callback that should be made the
+next time \index{quiescence}quiescence is detected.  \kw{CkStartQD} has two
+variants which expect the following arguments: 
+\begin{enumerate}
+\item 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{alltt}
+ CkStartQD(int Index,const CkChareID* chareID);
+\end{alltt}
+
+To retrieve the corresponding index of a particular \index{entry method}entry
+method, you must use a static method contained within the \uw{CkIndex} object
+corresponding to the \index{chare}chare containing that entry method.  The
+syntax of this call is as follows:
+
+\begin{alltt}
+\kw{myIdx}=CkIndex_\uw{ChareClass}::\uw{EntryMethod}(\uw{parameters});
+\end{alltt}
+
+where \uw{ChareClass} is the C++ class of the chare containing
+the desired entry method, \uw{EntryMethod} is the name of that entry method,
+and \uw{parameters} are the parameters taken by the method.
+These parameters are only used to resolve the proper \uw{EntryMethod};
+they are otherwise ignored.
+
+\item 
+A \uw{CkCallback} object. The syntax of this call looks like:
+\begin{alltt}
+  CkStartQD(const CkCallback& cb);
+\end{alltt}
+
+Upon quiescence detection, specified callback is called with no parameters.
+
+\end{enumerate}
+
+
+\kw{CkWaitQD}, by contrast, 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{alltt}
+  CkWaitQD();
+\end{alltt}
+
+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.
+