Fixed most of charm++ manual.
authorMilind Bhandarkar <milind@cs.uiuc.edu>
Wed, 27 Dec 2000 09:31:31 +0000 (09:31 +0000)
committerMilind Bhandarkar <milind@cs.uiuc.edu>
Wed, 27 Dec 2000 09:31:31 +0000 (09:31 +0000)
19 files changed:
doc/charm++/arrays.tex
doc/charm++/chares.tex
doc/charm++/further.tex
doc/charm++/groups.tex
doc/charm++/inhertmplt.tex
doc/charm++/intro.tex
doc/charm++/io.tex
doc/charm++/keywords.tex [deleted file]
doc/charm++/manual.tex
doc/charm++/messages.tex
doc/charm++/modules.tex
doc/charm++/nodegroups.tex
doc/charm++/othercalls.tex
doc/charm++/overview.tex
doc/charm++/quiesce.tex
doc/charm++/readonly.tex
doc/charm++/sdag.tex
doc/charm++/seqobjs.tex
doc/pplmanual.tex

index e1cb9adbe7cc0bd551265ff27958696b9ed52490..2ae50a125cf6a74e674cc3e23e56e9444549b758 100644 (file)
@@ -1,11 +1,11 @@
 \section{Chare Arrays}
 
-Chare arrays \index{arrays} are arbitrarily-sized collections of chares.
-The entire array is has a globally unique identifier of type 
-\kw{CkArrayID}, and each element has a unique index of type
-\kw{CkArrayIndex}.  A \kw{CkArrayIndex} can be a single integer (i.e., 1D
-array), several integers (i.e., a multidimentional array), or 
-an arbitrary string of bytes (e.g., a binary tree index).
+Chare arrays \index{arrays} are arbitrarily-sized collections of chares.  The
+entire array is has a globally unique identifier of type \kw{CkArrayID}, and
+each element has a unique index of type \kw{CkArrayIndex}.  A \kw{CkArrayIndex}
+can be a single integer (i.e. 1D array), several integers (i.e. a
+multidimentional array), or an arbitrary string of bytes (e.g. a binary tree
+index).
 
 In most respects, array elements are identical to chares.  Differences
 include variations in the creation and remote invocation syntax, to
@@ -20,42 +20,40 @@ contribute to array reductions.
 You can declare a one-dimentional \index{array}\index{chare array}chare array
 as:
 
-\begin{verbatim}
+\begin{alltt}
 //In the .ci file:
-array [1D] A {
+array [1D] A \{
   entry A();
   entry void someEntry(M1 *);
-};
+\};
 
 //In the .h file:
-class M1:public CMessage_M1 {
+class M1:public CMessage_M1 \{
 //...message fields...
-};
+\};
 
-class A : public ArrayElement1D {
+class A : public ArrayElement1D \{
   public:
     A(void);
     A(CkMigrateMessage *);
 
     void someEntry(M1 *);
-};
-\end{verbatim}
+\};
+\end{alltt}
 
-Note A's odd migration constructor, which is normally empty:
+Note \uw{A}'s odd migration constructor, which is normally empty:
 
-\begin{verbatim}
+\begin{alltt}
 //In the .C file:
 A::A(void)
-{
+\{
   //...your constructor code...
-}
-A::A(CkMigrateMessage *m) }
-\end{verbatim}
+\}
+A::A(CkMigrateMessage *m) \{ \}
+\end{alltt}
 
 Read the section ``Migratable Array Elements'' for more
-information on the \kw{CkMigrateMessage}
-constructor. 
-
+information on the \kw{CkMigrateMessage} constructor. 
 
 \subsection{Inserting and Destroying Array Elements}
 
@@ -65,28 +63,28 @@ routine.  You insert elements into the array with the
 the array with \kw{CProxy\_Array::doneInserting}.
 
 To create a 1D \index{array}array containing elements indexed 
-(0, 1, ..., num\_elements-1), you can use the shorter:
+(0, 1, ..., \uw{num\_elements}-1), you can use the shorter:
 
-\begin{verbatim}
+\begin{alltt}
 CProxy_A a = CProxy_A::ckNew(num_elements);
-\end{verbatim}
+\end{alltt}
 
-If A has a constructor that takes a message, you can use
+If \uw{A} has a constructor that takes a message, you can use
 
-\begin{verbatim}
+\begin{alltt}
 CProxy_A a = CProxy_A::ckNew(msg,num_elements);
-\end{verbatim}
-
+\end{alltt}
 
 If you don't have a 1D array or don't want a contiguous range
 of elements, you insert array elements dynamically using the 
 \kw{insert} and \kw{doneInserting} methods:
-\begin{verbatim}
-CProxy_A a = CProxy_A::ckNew();//<- note no arguments
-a[17].insert();//<- could also pass a message to constructor
-a[43].insert();//<- could use a different message or constructor here
+
+\begin{alltt}
+CProxy_A a = CProxy_A::ckNew(); //<- note no arguments
+a[17].insert(); //<- could also pass a message to constructor
+a[43].insert(); //<- could use a different message or constructor here
 a.doneInserting(); //<- needed because we used insert.
-\end{verbatim}
+\end{alltt}
 
 Insertion allows you to create sparse or multidimentional arrays,
 send a different message to each element, and specify the PE to create 
@@ -104,22 +102,24 @@ call actually does anything.  You may even \kw{insert} or \kw{destroy}
 elements after a call to \kw{doneInserting}, with different semantics-- 
 see the reduction manager and load balancer sections for details.
 
+To summarize, if your constructor takes no message, you can use \kw{ckNew} 
+and \kw{insert} as:
 
-To summarize, if your constructor takes no message, you can use \kw{ckNew} and \kw{insert} as:
-\begin{verbatim}
+\begin{alltt}
 With 1D elements: ckNew(numInitial); //<- doesn't need doneInserting
 No elements:      ckNew(); //<- will need doneInserting
 Default PE:       insert();
 Specific PE:      insert(onPE);
-\end{verbatim}
+\end{alltt}
 
 And if your constructor takes a message:
-\begin{verbatim}
+
+\begin{alltt}
 With 1D elements: ckNew(msg, numInitial); //<- doesn't need doneInserting
 No elements:      ckNew(); //<- will need doneInserting
 Default PE:       insert(msg);
 Specific PE:      insert(msg,onPE);
-\end{verbatim}
+\end{alltt}
 
 The system chooses the default PE to create an array element on
 based on the element's index: 1D indices map to processors in
@@ -127,47 +127,49 @@ a round-robin fashion; other indices map based on a hash function
 applied to the index.
 
 To destroy an array element-- detach it from the array
-call its destructor, and release its memory--invoke its ``destroy'' 
-entry point, as:
-\begin{verbatim}
+call its destructor, and release its memory--invoke its \kw{destroy} 
+entry method, as:
+
+\begin{alltt}
 a3(x,y,z).destroy();
-\end{verbatim}
+\end{alltt}
 
 After destroying an element, you may insert a new element at
 its index.
 
-
 \subsection{Messages and Broadcasts}
 
-\charmpp contains direct support for 1D, 2D, 3D, and user-defined
+\charmpp{} contains direct support for 1D, 2D, 3D, and user-defined
 index arrays.  These arrays can be declared as:
 
-\begin{verbatim}
+\begin{alltt}
 //In the .ci file:
 message MyMsg;
-array [1D] A1 {entry A1();entry void e(MyMsg *m);}
-array [2D] A2 {entry A2();entry void e(MyMsg *m);}
-array [3D] A3 {entry A3();entry void e(MyMsg *m);}
-array [Foo] AF {entry AF();entry void e(MyMsg *m);}
-\end{verbatim}
-
-The last declaration expects an array index of type CkArrayIndexFoo,
-which must be defined before including the .decl.h file 
-(see ``Defining a new array index type'' below).  Also, charm++.h must be included before the definition of the CkArrayIndexFoo type. 
-
-\begin{verbatim}
+array [1D] A1 \{ entry A1(); entry void e(MyMsg *m);\}
+array [2D] A2 \{ entry A2(); entry void e(MyMsg *m);\}
+array [3D] A3 \{ entry A3(); entry void e(MyMsg *m);\}
+array [Foo] AF \{ entry AF(); entry void e(MyMsg *m);\}
+\end{alltt}
+
+The last declaration expects an array index of type \uw{CkArrayIndexFoo},
+which must be defined before including the \texttt{.decl.h} file 
+(see ``Defining a new array index type'' below).  
+Also, \texttt{charm++.h} must be included before the definition of the 
+\uw{CkArrayIndexFoo} type. 
+
+\begin{alltt}
 //In the .h file:
-class MyMsg: public CMessage_MyMsg {
+class MyMsg: public CMessage_MyMsg \{
 public: 
   int val;
-  MyMsg(int i) {val=i;}
-}
-class A1:public ArrayElement1D {public: A1(){} ...};
-class A2:public ArrayElement2D {public: A2(){} ...};
-class A3:public ArrayElement3D {public: A3(){} ...};
-class AF:public ArrayElement {public: AF(){} ...};
+  MyMsg(int i) \{val=i;\}
+\}
+class A1:public ArrayElement1D \{ public: A1()\{\} ...\};
+class A2:public ArrayElement2D \{ public: A2()\{\} ...\};
+class A3:public ArrayElement3D \{ public: A3()\{\} ...\};
+class AF:public ArrayElement \{ public: AF()\{\} ...\};
 //(the migration constructors have been omitted for clarity)
-\end{verbatim}
+\end{alltt}
 
 You can insert elements or invoke methods on the elements of these
 arrays by specifying the array index in parentheses.  For 1D 
@@ -181,7 +183,7 @@ Messages sent to migrating elements will be delivered after
 the migrating element arrives.  It is an error to send 
 a message to a deleted array element.
 
-\begin{verbatim}
+\begin{alltt}
 //In the .C file:
 int x,y,z;
 CProxy_A1 a1=CProxy_A1::ckNew();
@@ -206,7 +208,8 @@ aF[new CkArrayIndexFoo(...)].insert();
 aF.doneInserting();
 aF[new CkArrayIndexFoo(...)].e(new MyMsg(7);
 
-\end{verbatim}
+\end{alltt}
+
 With user-defined index types, you must pass a fresh index 
 (allocated with new) to a [] or () call in order to create an element proxy.
 System will delete the index in the destructor for the element proxy.
@@ -214,9 +217,9 @@ System will delete the index in the destructor for the element proxy.
 To broadcast a message to all the current elements of an array, 
 simply omit the index, as:
 
-\begin{verbatim}
+\begin{alltt}
 a3.e(new MyMsg(7)); //<- invokes e(7) on each array element
-\end{verbatim}
+\end{alltt}
 
 \subsection{Migratable Array Elements}
 Array objects can \index{migrate}migrate from one PE to another.
@@ -225,9 +228,9 @@ might migrate array elements to better balance the load between
 processors.  For an array element to migrate, it must implement
 a pack/unpack or ``pup'' method:
 
-\begin{verbatim}
+\begin{alltt}
 //In the .h file:
-class A2:public ArrayElement2D {
+class A2:public ArrayElement2D \{
 private: //My data members:
     int nt;
     unsigned char chr;
@@ -237,21 +240,21 @@ private: //My data members:
 public:        
     //...other declarations
 
-    virtual void pup(PUP::er &p);
-};
+    virtual void pup(PUP::er \&p);
+\};
 
 //In the .C file:
-void A2::pup(PUP::er &p)
-{
-    ArrayElement2D::pup(p);//<- call superclass's pup routine
+void A2::pup(PUP::er \&p)
+\{
+    ArrayElement2D::pup(p); //<- call superclass's pup routine
     p(nt);
     p(chr);
     p(flt,7);
     p(numDbl);
     if (p.isUnpacking()) dbl=new double[numDbl];
     p(dbl,numDbl);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 You can apply a \kw{PUP::er} to any primitive variable
 (as with ``p(nt)'') or array of primitive variables-- there,
@@ -265,12 +268,12 @@ passing different types of \kw{PUP::er}s to it.  You can determine
 what type of \kw{PUP::er} has been passed to you with the
 \kw{isPacking()}, \kw{isUnpacking()}, and \kw{isSizing()} calls.
 
-An array element can migrate by calling the \uw{migrateMe(destination
-processor)} member function-- this call must be the last action
+An array element can migrate by calling the \kw{migrateMe}(\uw{destination
+processor}) member function-- this call must be the last action
 in an element entry point.  The system can also migrate array elements
 for load balancing (see the ``Load Balancing Chare Arrays'' chapter).
 
-To migrate your array element to another processor, the \charmpp 
+To migrate your array element to another processor, the \charmpp{}
 runtime will:
 
 \begin{itemize}
@@ -301,39 +304,39 @@ conversion if needed.
 To easily pack user-defined types, we recommend adding
 a \uw{pup} method to the user-defined type:
 
-\begin{verbatim}
+\begin{alltt}
 class myData 
-{
+\{
 private:
     int a,b;
     char c;
 public:
     ...
-    void pup(PUP::er &p) {
+    void pup(PUP::er \&p) \{
         p(a);
         p(b);
         p(c);
-    }
-};
+    \}
+\};
 
 //... array element can now easily pack myData as:
 class myElement:public ArrayElement1D 
-{
+\{
 private:
     myData d;
 public:
     ...
-    void pup(PUP::er &p)
-    {
-        ArrayElement1D::pup(p);//Call superclass
+    void pup(PUP::er \&p)
+    \{
+        ArrayElement1D::pup(p); //Call superclass
         d.pup(p); //<- pack/unpacks myData
-    }
-};
-\end{verbatim}
+    \}
+\};
+\end{alltt}
 
 
 \subsection{Load Balancing Chare Arrays}
-\charmpp includes a run-time load balancer which works
+\charmpp{} includes a run-time load balancer which works
 on array elements.  The idea is to run programs more efficiently
 by migrating array elements away from overloaded processors.
 To use the load balancer, you must make your elements migratable
@@ -352,7 +355,7 @@ an entry method.
 
 For the AtSync method, set \kw{usesAtSync} to true in your 
 array element constructor.  When an element is ready to migrate,
-call \kw{ArrayElement::AtSync}.  Once all elements have reached AtSync
+call \kw{ArrayElement::AtSync}.  Once all elements have reached \kw{AtSync}
 the load balancer runs and may migrate elements.  Once
 all migrations are complete, the load balancer calls 
 \kw{ArrayElement::ResumeFromSync}.  You must ensure no messages are
@@ -360,18 +363,18 @@ sent to an array element between its calls to \kw{AtSync} and
 \kw{ResumeFromSync}. \kw{AtSync}/\kw{ResumeFromSync} is currently
 a implemented as a global barrier.
 
-
-
 \subsection{Reductions on Chare Arrays}
 A \index{reduction}reduction applies a single operation (e.g. add,
 max, min, ...) to data items scattered across many processors and
-collects the result in one place.  \charmpp supports reductions on the
+collects the result in one place.  \charmpp{} supports reductions on the
 elements of a Chare array.
 
-The data to be reduced comes from each array element, which must call the contribute method:
-\begin{verbatim}
+The data to be reduced comes from each array element, 
+which must call the \kw{contribute} method:
+
+\begin{alltt}
 ArrayElement::contribute(int nBytes,void *data,ReducerType type);
-\end{verbatim}
+\end{alltt}
 
 This call contributes \kw{nBytes} bytes starting at \kw{data} to the
 reduction \kw{type} (see reduction types, below).  Unlike sending a
@@ -383,22 +386,26 @@ reduction will complete properly even if array elements are migrated
 or deleted.
 
 If we want to sum each array element's single integer myInt, we would use:
-\begin{verbatim}
+
+\begin{alltt}
     //Inside any array element method
     int myInt=get_myInt();
-    contribute(sizeof(int),(void *)&myInt,CkReduction::sum_int);
-\end{verbatim}
+    contribute(sizeof(int),(void *)\&myInt,CkReduction::sum_int);
+\end{alltt}
 
 The built-in reduction types (see below) can also handle arrays of
 numbers.  For example, if each element of an array has a pair of
 doubles \uw{forces}[2] which need to be summed up (separately) across
 all array elements, from each array element call:
-\begin{verbatim}
+
+\begin{alltt}
     //Inside any array element method
     double forces[2]=get_my_forces();
     contribute(2*sizeof(double),(void *)forces,CkReduction::sum_double);
-\end{verbatim}
-Note that since C++ arrays (like \uw{forces}[2]) are already pointers, we don't use (void *)\&forces.
+\end{alltt}
+
+Note that since C++ arrays (like \uw{forces}[2]) are already pointers, we 
+don't use (void *)\&\uw{forces}.
 
 
 After the data is reduced, it is passed to a ``client'' function on
@@ -406,20 +413,20 @@ node zero.  This is an ordinary C or C++ function that you pass to
 \kw{CProxy\_Array::setReductionClient}.  Reduction clients are
 typically registered from your main Chare's constructor, as in:
 
-\begin{verbatim}
+\begin{alltt}
 //Outside any class definition:
 void myClient(void *param,int dataSize,void *data)
-{
+\{
   double *forceSum=(double *)data;
   cout<<``First force sum is ``<<forceSum[0]<<endl;
   cout<<``Second force sum is ``<<forceSum[1]<<endl;
-}
+\}
 
 ...
     //Inside main::main
     CProxy_A a=CProxy_A::ckNew();
     a.setReductionClient(myClient,(void *)NULL);
-\end{verbatim}
+\end{alltt}
 
 This simple client prints out the double values received, and does not
 use the \uw{param} value passed in (\kw{NULL}, in this case).  The
@@ -428,7 +435,10 @@ fashion; but the data will be deleted after the handler returns.
 
 
 \subsection{Built-in Array Reduction Types}
-\charmpp includes several built-in reduction types, used to combine the contributions from different array elements.  Any of them may be passed as an \kw{ArrayReductionFn} type to \kw{ArrayElement::contribute}.
+
+\charmpp{} includes several built-in reduction types, used to combine the
+contributions from different array elements.  Any of them may be passed as an
+\kw{ArrayReductionFn} type to \kw{ArrayElement::contribute}.
 
 The first four reductions (sum, product, max, and min) work on int,
 float, or double data as indicated by the suffix.  The logical
@@ -438,127 +448,147 @@ pass the correct number of bytes to
 \kw{ArrayElement}::\kw{contribute}.
 
 \begin{enumerate}
-\item \kw{CkReduction::sum\_int}, \kw{\_float}, \kw{\_double}-- the result will be the sum of the given numbers.
 
-\item \kw{CkReduction::product\_int}, \kw{\_float}, \kw{\_double}-- the result will be the product of the given numbers.
+\item \kw{CkReduction::sum\_int}, \kw{sum\_float}, \kw{sum\_double}-- the
+result will be the sum of the given numbers.
+
+\item \kw{CkReduction::product\_int}, \kw{product\_float},
+\kw{product\_double}-- the result will be the product of the given numbers.
 
-\item \kw{CkReduction::max\_int}, \kw{\_float}, \kw{\_double}-- the result will be the largest of the given numbers.
+\item \kw{CkReduction::max\_int}, \kw{max\_float}, \kw{max\_double}-- the
+result will be the largest of the given numbers.
 
-\item \kw{CkReduction::min\_int}, \kw{\_float}, \kw{\_double}-- the result will be the smallest of the given numbers.
+\item \kw{CkReduction::min\_int}, \kw{min\_float}, \kw{min\_double}-- the
+result will be the smallest of the given numbers.
 
-\item \kw{CkReduction::and}-- the result will be the logical AND of the given integers.  0 is false, nonzero is true.
+\item \kw{CkReduction::and}-- the result will be the logical AND of the given
+integers.  0 is false, nonzero is true.
 
-\item \kw{CkReduction::or}-- the result will be the logical OR of the given integers.
+\item \kw{CkReduction::or}-- the result will be the logical OR of the given
+integers.
 
-\item \kw{CkReduction::set}-- the result will be a verbatim concatenation of all the contributed data, separated into \kw{CkReduction::setElement} records.  The data contributed can be of any length, and can vary across array elements or reductions.  To extract the data from each element, see the description below.
+\item \kw{CkReduction::set}-- the result will be a verbatim concatenation of
+all the contributed data, separated into \kw{CkReduction::setElement} records.
+The data contributed can be of any length, and can vary across array elements
+or reductions.  To extract the data from each element, see the description
+below.
 
 \end{enumerate}
 
 
-\kw{CkReduction::set} returns a collection of \kw{CkReduction::setElement} objects, one per contribution.  This class has definition:
-\begin{verbatim}
-class CkReduction::setElement {
+\kw{CkReduction::set} returns a collection of \kw{CkReduction::setElement}
+objects, one per contribution.  This class has definition:
+
+\begin{alltt}
+class CkReduction::setElement 
+\{
 public:
   int dataSize;//The length of the data array below
   char data[];//The (dataSize-long) array of data
   CkReduction::setElement *next(void);
-};
-\end{verbatim}
+\};
+\end{alltt}
+
+To extract the contribution of each array element from a reduction set, use the
+\uw{next} routine repeatedly:
 
-To extract the contribution of each array element from a reduction set, use the \uw{next} routine repeatedly:
-\begin{verbatim}
+\begin{alltt}
   //Inside a reduction handler-- 
   //  data is our reduced data from CkReduction_set
   CkReduction::setElement *cur=(CkReduction::setElement *)data;
   while (cur!=NULL)
-  {
+  \{
     ... //Use cur->dataSize and cur->data
     //Now advance to the next element's contribution
     cur=cur->next();
-  }
-\end{verbatim}
+  \}
+\end{alltt}
 
-The reduction set order is undefined.  Add a source field to your contribution if you need to know which array element gave a particular contribution.
+The reduction set order is undefined.  Add a source field to your contribution
+if you need to know which array element gave a particular contribution.
 
 \subsection{Defining a new array index type}
-\charmpp array indices are arbitrary collections of bytes.
+
+\charmpp{} array indices are arbitrary collections of bytes.
 To define a new array index, you create an ordinary C++ class 
 which inherits from \kw{CkArrayIndex} and overrides the \kw{getKey} method.  
 For example, if you have a structure or class named ``foo'', you 
 can use a \uw{foo} object as an array index by defining the class:
 
-\begin{verbatim}
-class CkArrayIndexFoo:public CkArrayIndex {
+\begin{alltt}
+class CkArrayIndexFoo:public CkArrayIndex \{
 public:
     foo f;
 
-    CkArrayIndexFoo(const foo &in) {f=in;}
+    CkArrayIndexFoo(const foo \&in) \{f=in;\}
 
     //This method returns the length of and a pointer to the index data.
     //The returned pointer must be aligned to at least an integer boundary.
-    virtual const unsigned char *getKey(/*out*/ int &nBytes) const {
+    virtual const unsigned char *getKey(/*out*/ int \&nBytes) const \{
        nBytes=sizeof(foo);
-        return (const unsigned char *)&f;
-    }
-};
-\end{verbatim}
+        return (const unsigned char *)\&f;
+    \}
+\};
+\end{alltt}
 
 You can then declare an array indexed by \uw{foo} objects with
 
-\begin{verbatim}
+\begin{alltt}
 //in the .ci file:
-array [Foo] AF {entry AF(); ... }
+array [Foo] AF \{ entry AF(); ... \}
 
 //in the .h file:
-class AF:public ArrayElement {public: AF() {} ... }
+class AF:public ArrayElement \{ public: AF() \{\} ... \}
 
 //in the .C file:
     foo f;
     CProxy_AF a=CProxy_AF::ckNew();
     a[new CkArrayIndexFoo(f)].insert();
     ...
-\end{verbatim}
+\end{alltt}
 
 Inside an \kw{ArrayElement}, you can get the bytes of your index
 from the ``thisindex'' variable, which has type \kw{CkArrayIndexGeneric*}.  
 It may be more convenient, however, to inherit from \kw{ArrayElementT} a 
-class templated in the index type foo (stored as ``thisIndex'').
+class templated in the index type \uw{foo} (stored as ``thisIndex'').
 For example:
 
-\begin{verbatim}
+\begin{alltt}
 //.ci file unchanged
 //in the .h file:
-class AF:public ArrayElementT<foo> {public: AF() {} ... }
+class AF:public ArrayElementT<foo> \{public: AF() \{\} ... \}
 
 //in the .C file:
 AF::AF()
-{
+\{
     foo myF=thisIndex;
     functionTakingFoo(myF);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 
 \subsection{Array Syntax Changes}
+
 The syntax for arrays changed in April, 2000 in the following ways:
 
 \begin{itemize}
 
-\item CkAID is obsolete, and replaced with CkArrayID.  In general,
-you should now use CProxy's instead of CkArrayID's because the syntax
+\item \kw{CkAID} is obsolete, and replaced with \kw{CkArrayID}.  In general,
+you should now use CProxy's instead of \kw{CkArrayID}'s because the syntax
 is more palatable and the compiler can do static type checking.
 
 \item The translator syntax for arrays now includes the index type,
-e.g. ``array [1D] foo { ... }''.
+e.g. ``array [1D] foo \{ ... \}''.
 
 \item Messages sent to array elements need no longer inherit from 
 \kw{ArrayMessage}.
 
-\item Array elements for 1D arrays must inherit from ArrayElement1D
-to use a 1D thisIndex.  You may still inherit from ArrayElement, but you
-won't have a thisIndex.
+\item Array elements for 1D arrays must inherit from \kw{ArrayElement1D} to use
+a 1D \kw{thisIndex}.  You may still inherit from \kw{ArrayElement}, but you
+won't have a \kw{thisIndex}.
 
-\item You may have multiple array constructors; each can now take a user-defined message, or no message.  
+\item You may have multiple array constructors; each can now take a
+user-defined message, or no message.  
 
 \item The \kw{ArrayElementCreateMessage} constructor is obsolete;
 as are the \kw{finishConstruction} and \kw{finishMigration} calls. No
@@ -571,12 +601,15 @@ constructor need explicitly call its superclass.
 the migration constructor have been replaced by a unified pack/unpack 
 ``pup'' routine.
 
-\item For load balancing, the \kw{uses\_at\_sync} variable is now called \kw{usesAtSync}.
+\item For load balancing, the \kw{uses\_at\_sync} variable is now called
+\kw{usesAtSync}.
+
+\item \kw{CkReduction\_sum\_int} is now an enumeration, not a function pointer,
+and now called \kw{CkReduction::sum\_int}.
 
-\item \kw{CkReduction\_sum\_int} is now an enumeration, not a function pointer, and now called \kw{CkReduction::sum\_int}.
+\item \function{CkRegisterArrayReductionHandler(proxy,fn,param)} is now
+proxy.setReductionClient(fn,param). 
 
-\item \function{CkRegisterArrayReductionHandler(proxy,fn,param)}
-is now proxy.setReductionClient(fn,param).
 \end{itemize}
 
 
index 9f1fea961f40a01122a266380cda3fd3c7e3551e..3be3e34cac410e43f7b3bfa5da6e0c57d9965d7b 100644 (file)
@@ -2,32 +2,30 @@
 
 \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:
+must be specified in the interface (\texttt{.ci}) file:
 
-\begin{tabbing}
-~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
-\> \kw{chare} \uw{ChareType} \{ \\
-\> \> \kw{entry} \uw{ChareType}(\uw{MessageType1} *); \\
-\> \> \kw{entry void} \uw{EntryMethodName2}(\uw{MessageType2} *); \\
-\> \};
-\end{tabbing}
+\begin{alltt}
+chare ChareType
+\{
+    entry   ChareType             (MessageType1 *);
+    entry   void EntryMethodName2 (MessageType2 *);
+\};
+\end{alltt}
 
-A corresponding \index{chare}chare definition in the {\tt .h} file would 
+A corresponding \index{chare}chare definition in the \texttt{.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}
+\begin{alltt}
+   class ChareType : public Chare [: superclass names] \{   
+        // Data and member functions as in C++ 
+        // One or more entry methods definitions of the form: 
+   public: 
+      ChareType(MessageType1 *MsgPointer) 
+         \{ // C++ code block  \} 
+      void EntryMethodName2(MessageType2 *MsgPointer) 
+         \{ // C++ code block  \} 
+   \};
+\end{alltt}
 
 \index{chare}
 Chares are concurrent objects encapsulating medium-grained units of
@@ -42,17 +40,17 @@ 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
+The entry method definition specifies a function that is executed {\em
 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
+methods are defined exactly as normal \CC{} 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.
+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}
+Each chare instance is identified by a {\em handle} \index{handle}
 which is essentially a global pointer, and is unique across all
 processors.  The handle of a chare has type \kw{CkChareID}.  The
 variable \kw{thishandle} holds the handle of the
@@ -65,45 +63,43 @@ mechanism allows chares to send their handles to other chares.
 \subsection{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 earlier. The following is an example of
+First, a \index{chare}chare needs to be declared, both in \texttt{.ci} file and
+in \texttt{.h} file, as stated earlier. 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:
+In the \texttt{mod.ci} file we have:
 
-\begin{verbatim}
-module mod {
-  chare C {
+\begin{alltt}
+module mod \{
+  chare C \{
     entry C(M1 *);
     entry void someEntry(M2 *);
-  };
-}
-\end{verbatim}
+  \};
+\}
+\end{alltt}
 
-and in the {\tt mod.h} file:
+and in the \texttt{mod.h} file:
 
-\begin{verbatim}
+\begin{alltt}
 #include "mod.decl.h"
-class C : public Chare {
+class C : public Chare \{
   public:
     C(M1 *);
     void someEntry(M2 *);
-};
-\end{verbatim}
+\};
+\end{alltt}
 
-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}:
+Now one can use the class \kw{CProxy}\_\uw{chareType} 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}
+\begin{alltt}
+   CProxy_chareType::ckNew(MessageType *msgPtr, CkChareID *vHdl, int destPE);
+\end{alltt}
 
 where each parameter above is optional and where
 
@@ -112,13 +108,13 @@ where each parameter above is optional and where
 \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
+\item \uw{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
+\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
+\item \uw{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
@@ -131,10 +127,10 @@ 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
+\item \uw{destPE}: when a \index{chare}chare is to be created at a specific
+processor, the \uw{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.
+\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
@@ -156,35 +152,34 @@ 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}
+\item{This will create a new \index{chare}chare of type \uw{C} on {\em any}
+processor:}
+
+\begin{alltt}
+   MessageType *MsgPtr = new MessageType;
+   CProxy_C *pC = new CProxy_C(MsgPtr);
+      // or
+   MessageType *MsgPtr = new MessageType;
+   CProxy_C::ckNew(MsgPtr);
+\end{alltt} 
+
+\item{This will create a new \index{chare}chare of type \uw{C} on processor
+\kw{destPE}:}
+
+\begin{alltt}
+   MessageType *MsgPtr = new MessageType;
+   CProxy_C::ckNew(MsgPtr, destPE);
+\end{alltt}
+
+\item{The following first creates a \kw{CkChareID} \uw{cid},
+then creates a new \index{chare}chare of type \uw{C} on processor \uw{destPE}:}
+
+\begin{alltt}
+   MessageType *MsgPtr = new MessageType;
+   CkChareID cid;
+   CProxy_C::ckNew(MsgPtr, \&cid, destPE);
+   CProxy_C c(cid);
+\end{alltt}
 
 \end{enumerate}
 
@@ -196,30 +191,32 @@ 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 \kw{CkChareID}.
 
-\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
-\=~~~~ \kill \> \kw{CProxy}\_\uw{chareType} {\it chareProxy}({\it chareID});
-\end{tabbing}
+\begin{alltt}
+   CProxy_chareType chareProxy(chareID);
+\end{alltt}
 
-This declares a proxy named {\it chareProxy} of \uw{chareType} using {\it
-chareID}.  Alternatively, we can create a proxy pointer:
+This declares a proxy named \uw{chareProxy} of \uw{chareType} 
+using \uw{chareID}.  Alternatively, we can create a proxy pointer:
 
-\begin{tabbing} ~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~
-\=~~~~ \kill \> \kw{CProxy}\_\uw{chareType} *{\it chareProxyPointer} = \kw{new
-CProxy}\_\uw{chareType}({\it chareID}); \end{tabbing}
+\begin{alltt}
+CProxy_chareType *chareProxyPointer = new CProxy_chareType(chareID);
+\end{alltt}
 
-This creates a pointer named {\it chareProxyPointer} which points to the proxy. 
+This creates a pointer named \uw{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})
+\begin{tabbing}
+chareProxy.EntryMethod(MessagePointer)
+or,
+chareProxyPointer->EntryMethod(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},
+This sends the message pointed to by \uw{MessagePointer} to the
+\index{chare}chare whose proxy/proxy pointer is 
+\uw{chareProxy}/\uw{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. 
index 2484c9c91a5d035c549cdcaa5a7de585acbcad02..b32023a66d61636c16ad0f207e447b45af9b40a0 100644 (file)
@@ -5,45 +5,46 @@
 
 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/}. 
+Laboratory website: \texttt{http://charm.cs.uiuc.edu/}. 
 
 \section{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
+Several tools and libraries are provided for \charmpp{}. \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.
+Most of the libraries have been described in a separate manual.
 
-\subsection{Projections}
-{\bf Projections} is a
-performance visualization and feedback tool. The system has a much
-more refined understanding of user computation than is possible in
+\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
 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. 
+\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.
+Future versions will be able to provide recommendations/suggestions for
+improving performance as well.
 
 \subsection{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.
+
+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
+was needed. Moreover, it was needed to automatically adapt the strategy to the
+situation at hand. The collective 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.
 
 \section{Contacts}
 \label{Distribution}
@@ -56,27 +57,20 @@ 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
+For the latest software distribution, further information about
+\converse{}/\charmpp\ and information on how to contact the Parallel
+Programming laboratory, see our website at \texttt{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}
-}
+please send electronic mail to \texttt{kale@cs.uiuc.edu} or postal mail to:
 
-A mailing list exists for announcements about software releases and
-updates relating to \charmpp/{\sc Converse}.  To subscribe, send
-e-mail to: ???????.
+\begin{alltt}
+   Laxmikant Kale
+   Department of Computer Science 
+   University of Illinois 
+   1304 West Springfield Avenue 
+   Urbana, IL 61801 
+\end{alltt}
index fbd1cd49c5dab949015bedd872ec7f108f4d0fcf..fcf6c5d6cbf2f5f77e28b3b7bb53888e717ffc34 100644 (file)
@@ -1,7 +1,7 @@
 \section{Group Objects}
 
-A {\sl group\footnote{Originally called {\em Branch Office Chare} or 
-{\em Branched Chare}}} \index{group}is a collection of chares where 
+A \kw{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
@@ -10,71 +10,66 @@ inherit from the system defined class \kw{Group}, rather than
 
 In the interface file, we declare
 
-\begin{tabbing}
-~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
-\> \kw{group} \uw{GroupType} \{ \\
-\> \>  // Interface specifications as for normal chares \\
-\> \};
-\end{tabbing}
+\begin{alltt}
+ group GroupType \{
+   // Interface specifications as for normal chares
+ \};
+\end{alltt}
 
-In the {\tt .h} file, we define \uw{GroupType} as follows:
+In the \texttt{.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}
+\begin{alltt}
+ class GroupType : public Group [,other superclasses ] \{
+  // Data and member functions as in C++
+  // Entry functions as for normal chares
+ \};
+\end{alltt}
 
 A group is identified by a globally unique group identifier, whose type is
-\kw{CkGroupID}. This identifier is common to all of the 
-group's branches and can be obtained from the variable \kw{thisgroup},
- which is a public local variable of the \kw{Group} 
-superclass.  For groups, \kw{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.  There can be many
-instances corresponding to a group type.  Each instance has a
-different group handle, and its own set of branches.
+\kw{CkGroupID}. This identifier is common to all of the group's branches and
+can be obtained from the variable \kw{thisgroup}, which is a public local
+variable of the \kw{Group} superclass.  For groups, \kw{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.  There can be many instances corresponding
+to a group type.  Each instance has a different group handle, and its own set
+of branches.
 
 \subsection{Group Creation}
 
-\noindent {\bf Chare Group Declaration}:
+Given a \texttt{.ci} file as follows:
 
-\noindent Given a {\tt .ci} file as follows:
-
-\begin{verbatim}
-group G {
+\begin{alltt}
+group G \{
   entry G(M1 *);
   entry void someEntry(M2 *);
-};
-\end{verbatim}
+\};
+\end{alltt}
 
-\noindent and the following {\tt .h} file:
+and the following \texttt{.h} file:
 
-\begin{verbatim}
-class G : public Group {
+\begin{alltt}
+class G : public Group \{
   public:
     G(M1 *);
     void someEntry(M2 *);
-};
-\end{verbatim}
+\};
+\end{alltt}
 
-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.
+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}
+\begin{alltt}
 M1 *m1 = new M1;
 CProxy_G *pG = new CProxy_G(m1);
   // or
 CkGroupID gid = CProxy_G::ckNew(m1);
 CProxy_G g(gid);
-\end{verbatim}
+\end{alltt}
 
 \subsection{Method Invocation on Groups}
 
@@ -83,38 +78,41 @@ method, we need to get a proxy of that group using the group identifier (a
 \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}
+\begin{alltt}
+ CProxy_groupType groupProxy(groupID);
+  or,
+ CProxy_groupType *groupProxyPointer = new CProxy_groupType(groupID);
+\end{alltt}
 
-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}. 
+The first approach creates a proxy to the group represented by \uw{groupID}
+while the second creates a pointer named \uw{groupProxyPointer} to a proxy to
+the group represented by \uw{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}
+\begin{alltt}
+ groupProxy.EntryMethod(MessagePointer, Processor)
+  or,
+ groupProxyPointer->EntryMethod(MessagePointer, Processor)
+\end{alltt}
 
-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
+This sends the message in \uw{MessagePointer} to the \index{branch}branch of
+the group represented by \uw{groupID} which is on processor number
+\uw{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}
+\begin{alltt}
+ groupProxy.EntryMethod(MessagePointer)
+ groupProxyPointer->EntryMethod(MessagePointer)
+\end{alltt}
 
-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
+This sends the message in \uw{MessagePointer} to all branches of the group 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.
 
@@ -126,32 +124,38 @@ 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}(). 
+\begin{alltt}
+((GroupType*)CkLocalBranch(CkGroupID groupID))->DataMember
+{\em and} 
+(GroupType*)CkLocalBranch(CkGroupID groupID))->method() 
+\end{alltt}
 
 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.  Once a proxy to the local branch of a group is obtained, that branch can be thought of as a regular object.  Its public methods can return values, and its public data is readily accessible.   
-
-\kw{CkLocalBranch} returns a generic ({\tt void
-*}) pointer.  It needs to be
-cast to a pointer of appropriate classe before invoking methods or
-accessing data members. \charmpp\ provides another way to do this using
-the generated
+executes in the local \index{branch}branch of the group.  Once a proxy to the
+local branch of a group is obtained, that branch can be thought of as a regular
+object.  Its public methods can return values, and its public data is readily
+accessible.   
+
+\kw{CkLocalBranch} returns a generic (\texttt{void *}) pointer.  It needs to be
+cast to a pointer of appropriate classe before invoking methods or accessing
+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} of the proxy class of appropriate
-group 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{ckLocalBranch} of the proxy class of appropriate group 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}(...);\\
+\begin{alltt}
+(CProxy_G::ckLocalBranch(gid))->foo(...);
+\end{alltt}
 \index{ckLocalBranch}
 
-One very nice use of Groups is to reduce the number of messages sent between processors by collecting the data from all the chares on a single processor before sending that data to the mainchare.  To do this, create basic chares to break up the work of a problem.  Also, create a group.  When a particular chare finishes its work, it reports its findings to the local branch of the group.  When all the chares on one processor are complete, the local branch of the group can then report to the main chare.  This reduces the number of messages sent to main from the number of chares created to the number of processors.     
-
-
-
-
-
+One very nice use of Groups is to reduce the number of messages sent between
+processors by collecting the data from all the chares on a single processor
+before sending that data to the mainchare.  To do this, create basic chares to
+break up the work of a problem.  Also, create a group.  When a particular chare
+finishes its work, it reports its findings to the local branch of the group.
+When all the chares on one processor are complete, the local branch of the
+group can then report to the main chare.  This reduces the number of messages
+sent to main from the number of chares created to the number of processors.     
 
index d780c348cf1d488f2f9bd00083b0b2d456766682..1720f7ac62e2a4a53dd98098a892db11db256f51 100644 (file)
@@ -1,32 +1,33 @@
 \chapter{Inheritance and Templates in Charm++}
 \label{inheritance and templates}
 
-\charmpp\ 5.0 supports inheritance among \charmpp\ objects such as
+\charmpp\ 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.
+major enhancement over the previous versions of \charmpp.
 
 \section{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:
+\uw{BaseChare}. Thus, the constructs in the \texttt{.ci} file should look like:
 
-\begin{verbatim}
-  chare BaseChare {
+\begin{alltt}
+  chare BaseChare \{
     BaseChare(someMessage *);
     baseMethod(void);
     ...
-  }
-  chare DerivedChare : BaseChare {
+  \}
+  chare DerivedChare : BaseChare \{
     DerivedChare(otherMessage *);
     derivedMethod(void);
     ...
-  }
-\end{verbatim}
+  \}
+\end{alltt}
 
 Note that the access specifier \kw{public} is omitted, because \charmpp\
 interface translator only needs to know about the public inheritance,
@@ -37,26 +38,26 @@ invoke only \kw{public} methods.
 
 The class definitions of both these chares should look like:
 
-\begin{verbatim}
-  class BaseChare : public Chare {
+\begin{alltt}
+  class BaseChare : public Chare \{
     // private or protected data
     public:
       BaseChare(someMessage *);
       baseMethod(void);
-  };
-  class DerivedChare : public BaseChare {
+  \};
+  class DerivedChare : public BaseChare \{
     // private or protected data
     public:
       DerivedChare(otherMessage *);
       derivedMethod(void);
-  };
-\end{verbatim}
+  \};
+\end{alltt}
 
 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}
+\begin{alltt}
   ...
   otherMessage *msg = new otherMessage();
   CProxy_DerivedChare *pd = new CProxy_DerivedChare(msg);
@@ -66,32 +67,30 @@ as shown below:
   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.
+\end{alltt}
+
+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.
 
 \section{Inheritance for Messages}
 \index{message inheritance}
@@ -99,54 +98,47 @@ class instance.
 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.
+Message inheritance makes it possible to send a message of derived type to the
+method expecting a base class message.
 
 \section{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}. 
-}. 
+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
@@ -155,12 +147,12 @@ class \uw{TMessage} is templated with a formal type parameter
 in the \charmpp\ interface file. An example will illustrate this better:
 \index{template}
 
-\begin{verbatim}
+\begin{alltt}
   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}
+\end{alltt}
 
 Note the use of default template parameters. It is not necessary for
 template definitions and template instantiations to be part of the
@@ -170,32 +162,31 @@ 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 {
+\begin{alltt}
+module SCTL \{
   template <class dtype> message  Singleton;
-  template <class dtype> group Reducer {
+  template <class dtype> group Reducer \{
     entry Reducer(void);
     entry void submit(Singleton<dtype> *);
-  }
-  template <class dtype> chare ReductionClient {
+  \}
+  template <class dtype> chare ReductionClient \{
     entry void recvResult(Singleton<dtype> *);
-  }
-};
+  \}
+\};
 
-module User {
+module User \{
   extern module SCTL;
   message Singleton<int>;
   group Reducer<int>;
   chare RedcutionClient<int>;
-  chare UserClient : ReductionClient<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.
+  \}
+\};
+\end{alltt}
+
+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.
index 2c9280b6bb4defe0394d34775f15e9a55f934533..a28bcb223239fed03146e606f55236dffeab3d65 100644 (file)
@@ -1,7 +1,5 @@
 \chapter{Introduction}
 
-%update as you wish
-
 This manual describes \charmpp, an object oriented portable parallel
 programming language based on \CC. Its program structure, execution
 model, interface language constructs and runtime system calls are
@@ -17,14 +15,13 @@ philosophy please refer to the following papers :\\
     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 earlier
 versions modified the \CC\ syntax to support \charmpp\ primitives, and
 contained a full-fledged \charmpp\ translator that parsed the \charmpp\
 syntactic extensions as well as the \CC\ syntax to produce a \CC\ program,
 which was later compiled using a \CC\ compiler.  The current version does not
-augment the C++ syntax, and does not use a \charmpp\ translator as in previous
+augment the \CC{} syntax, and does not use a \charmpp\ translator as in previous
 versions. Instead, the older constructs are converted to calls into the runtime
 library, several new constructs are added, and minimal language constructs are
 used to describe the interfaces.
@@ -43,20 +40,12 @@ 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.}.
+run without changing the source on all these platforms.  Please see the
+\charmpp{}/\converse{} Installation and Usage Manual for details about
+installing, compiling and running \charmpp\ programs.
 
 \section{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.
@@ -83,10 +72,10 @@ The programmer-visible entities in a \charmpp\ program are:
 \end{itemize}
 
 \charmpp\ starts a program by creating a single \index{chare} instance of each
-{\em mainchare} on processor 0, and invokes constructor methods of these chare.
-Typically, these chares then creates a number of other \index{chare} chares,
-possibly on other processors, which can simultaneously work to solve the
-problem at hand.
+{\em mainchare} on processor 0, and invokes constructor methods of these
+chares.  Typically, these chares then creates a number of other \index{chare}
+chares, possibly on other processors, which can simultaneously 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
@@ -113,8 +102,6 @@ The following sections provide detailed information about various features of
 
 \section{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.
 Researchers at the Parallel Programming Laboratory keep \charmpp\ updated for
@@ -148,25 +135,6 @@ 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.
-
-
-\section{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: \kw{chare}.
-\item User-defined types and function names appear in a sans serif font:
-\uw{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. 
-
-
-
+\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 0f6261c087dfbe801f6719ce7575f00839e2b639..b9238a690474c4dd486919e91c7f76dc6aa07cba 100644 (file)
@@ -3,20 +3,20 @@
 \index{input/output}
 \charmpp\ provides both C and \CC\ style methods of doing terminal I/O.  
 
-In the place of C-style printf and scanf, \charmpp\ provides
+In place of C-style printf and scanf, \charmpp\ provides
 \kw{CkPrintf} and \kw{CkScanf}.  These functions have
 interfaces that are identical to their C counterparts, but there are some
 differences in their behavior that should be mentioned.
 
-\function{int CkPrintf(format [, arg]*)} \index{CkPrintf} \index{input/output} \\
+\function{int CkPrintf(format [, arg]*)} \index{CkPrintf} \index{input/output}
 \desc{This call is used for atomic terminal output. Its usage is similar to
-{\sf printf} in C.  However, \kw{CkPrintf} has some special properties
+\texttt{printf} in C.  However, \kw{CkPrintf} has some special properties
 that make it more suited for parallel programming on networks of
-workstations.  \kw{CkPrintf} routes all terminal output to the processor 0,
-which is the one running the host program.  So, if a
+workstations.  \kw{CkPrintf} routes all terminal output to the \kw{charmrun},
+which is running on the host computer.  So, if a
 \index{chare}chare on processor 3 makes a call to \kw{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
+puts the output in a TCP message and sends it to host
+computer where it will be displayed.  This message passing is an asynchronous
 send, meaning that the call to \kw{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
@@ -26,14 +26,15 @@ processor 2.  After chare 2's creation, it calls \kw{CkPrintf}, and the
 message from chare 2 is displayed before the one from chare 1.}
 }
 
-\function{void CkError(format [, arg]*))} \index{CkError} \index{input/output} \\
-\desc{Like \kw{CkPrintf}, but used to print error messages.}
+\function{void CkError(format [, arg]*))} \index{CkError} \index{input/output} 
+\desc{Like \kw{CkPrintf}, but used to print error messages on \texttt{stderr}.}
 
-\function{int CkScanf(format [, arg]*)} \index{CkScanf} \index{input/output} \\
+\function{int CkScanf(format [, arg]*)} \index{CkScanf} \index{input/output}
 \desc{This call is used for atomic terminal input. Its usage is similar to
-{\sf scanf} in C.  A call to \kw{CkScanf}, unlike \kw{CkPrintf},
+{\tt scanf} in C.  A call to \kw{CkScanf}, unlike \kw{CkPrintf},
 blocks all execution on the processor it is called from, and returns
 only after all input has been retrieved.
+}
 
 For \CC\ style stream-based I/O, \charmpp\ offers \kw{ckin},
 \kw{ckout}, and \kw{ckerr} in the place of cin, cout, and cerr.  The
@@ -43,7 +44,4 @@ manner as printf and scanf are to \kw{CkPrintf} and \kw{CkScanf}.  The
 streams, and all behave in a slightly different way, just like C-style
 I/O. \kw{ckout} and \kw{ckerr} both have the same idiosyncratic
 behavior as \kw{CkPrintf}, and \kw{ckin} behaves in the same way as
-\kw{CkScanf}.}
-
-
-
+\kw{CkScanf}.
diff --git a/doc/charm++/keywords.tex b/doc/charm++/keywords.tex
deleted file mode 100644 (file)
index b606f43..0000000
+++ /dev/null
@@ -1,97 +0,0 @@
-\chapter{\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 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}
index 2ad241aff4ba84ca4d95f837b0b650eaba2dc415..2c58053db5f2a12136db66eeb1448e2a1bbbf685 100644 (file)
@@ -45,6 +45,8 @@ Brunner), and SGI Origin2000 (Milind Bhandarkar).  The test suite for
 \charmpp\ 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.
+Orion Lawlor, Gengbin Zheng, and Milind Bhandarkar have been responsible
+for the changes to the system since the last release.
 }
 }
 
@@ -73,8 +75,6 @@ redesigned and rewritten using Java by Michael Denardo.
 
 \appendix
 
-\input{keywords}
-
 \input{sdag}
 
 \input{further}
index 51ea35b0eb7ecd764a2e5038e50a580b965b2dd1..81df6abaae6f6aec1847157a18d02a5aef21fd54 100644 (file)
@@ -1,53 +1,46 @@
 \section{Messages}
 
 In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
-nodegroups communicate using 
-messages. Sending a message \index{message} to an object corresponds to an 
-asynchronous method invocation.
-Several variations on messaging are available, regular \charmpp messages are 
-objects of \textit{fixed size}. If you want your message object to contain 
-pointers to dynamically allocated memory and need these to be valid when 
-messages are sent across processors you must declare your messages to be 
-\kw{varsize} (variable size) or \kw{packed} messages, which need some 
-additional processing. Though similar in nature, they vary in the amount 
-of flexibilty they provide in terms of representing arbitrary data structures.
-Also available is a mechanism for assigning \textit{priorities} to messages 
-that applies all kinds of messages, a detailed discussion
-of priorities appears later in this section.
-
-Like all 
-other entities involved in asynchronous method invocation, messages need to be
-declared in the {\tt .ci} file.
-
-Message definitions that may appear in the {\tt .h} or {\tt .C} file are very 
-similar to class definitions in C++.
+nodegroups communicate using messages. Sending a message \index{message} to an
+object corresponds to an asynchronous method invocation.  Several variations on
+messaging are available, regular \charmpp{} messages are objects of
+\textit{fixed size}. If you want your message object to contain pointers to
+dynamically allocated memory and need these to be valid when messages are sent
+across processors you must declare your messages to be \kw{varsize} (variable
+size) or \kw{packed} messages, which need some additional processing. Though
+similar in nature, they vary in the amount of flexibilty they provide in terms
+of representing arbitrary data structures.  Also available is a mechanism for
+assigning \textit{priorities} to messages that applies all kinds of messages, a
+detailed discussion of priorities appears later in this section.
+
+Like all other entities involved in asynchronous method invocation, messages
+need to be declared in the {\tt .ci} file.
+
+Message definitions that may appear in the {\tt .h} or {\tt .C} file are very
+similar to class definitions in \CC.
 
 In the {\tt .ci} file (the interface file), a message is declared as: 
 
-\begin{tabbing}
-~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
-\> \kw{message} \uw{MessageType};
-\end{tabbing}
+\begin{alltt}
+ message MessageType;
+\end{alltt}
 
 a variable sized or packed message is declared as:
 
-\begin{tabbing}
-~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \=~~~~ \kill
-\> \kw{message} [varsize|packed] \uw{MessageType};
-\end{tabbing}
+\begin{alltt}
+ message [varsize|packed] MessageType;
+\end{alltt}
 
 
 If the name of the message class is \uw{MessageType}, the class must inherit 
-publicly from a class whose name is \kw{CMessage}\_\uw{MessageType}. This class
+publicly from a class whose name is \uw{CMessage\_MessageType}. This class
 is generated by the charm translator. Then 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}
+\begin{alltt}
+ class MessageType : public CMessage_MessageType \{
+    // List of data and function members as in \CC
+ \};
+\end{alltt}
 
 
 \subsection{Message Creation and Deletion}
@@ -55,66 +48,63 @@ is generated by the charm translator. Then message definition has the form:
 
 \index{message}Messages are allocated using the \CC\ \kw{new} operator:
 
-\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}
-
-The optional arguments to the new operator are used when allocating 
-\kw{varsize} or \kw{prioritized} messages. The {\it sizes\_array} 
-used for varsize messages is an 
-array of integer elements of which denote the size (in appropriate
-units) of the memory blocks that need to be allocated and assigned to the
-pointers that the message contains. The {\it priobits} argument 
-denotes the size of a bitfield that will be used to store the message 
-priority.   
+\begin{alltt}
+ MessageType *msgptr =
+  new [((int *)sizes_array, int priobits=0)] MessageType[(constructor arguments)];
+\end{alltt}
+
+The optional arguments to the new operator are used when allocating
+\kw{varsize} or \kw{prioritized} messages. The \uw{sizes\_array} used for
+varsize messages is an array of integer elements of which denote the size (in
+appropriate units) of the memory blocks that need to be allocated and assigned
+to the pointers that the message contains. The \uw{priobits} argument denotes
+the size of a bitfield that will be used to store the message priority.   
 
 For example, to allocate a \index{varsize message}varsize message whose 
 class declaration is:
 
-\begin{verbatim}
-class VarsizeMessage : public CMessage_VarsizeMessage{
+\begin{alltt}
+class VarsizeMessage : public CMessage_VarsizeMessage \{
   int length;
   int *firstArray;
   double *secondArray;
-};
-\end{verbatim}
+\};
+\end{alltt}
 
 assign the size array and allocate the message:
-\begin{verbatim}
+
+\begin{alltt}
 int size[2];
 size[0] = 10;
 size[1] = 20;
 VarsizeMessage *msg = new (size,0) VarsizeMessage;
-\end{verbatim}
-
-This allocates a {\it VarsizeMessage}, in which (typically) {\it firstArray}
-points to an array of 10 ints and {\it secondArray} points to an array
-of 20 doubles. We say typically because the programmer has full control over 
-how the sizes array is used. The meaning of this will be made clear in the 
-section on variable sized messages.
+\end{alltt}
 
+This allocates a \uw{VarsizeMessage}, in which {\em typically} \uw{firstArray}
+points to an array of 10 ints and \uw{secondArray} points to an array of 20
+doubles. We say typically because the programmer has full control over how the
+sizes array is used. The meaning of this will be made clear in the section on
+variable sized messages.
 
 To add a \index{priority}priority bitfield to this message, 
-\begin{verbatim}
+
+\begin{alltt}
 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. The section on prioritized execution describes
-how this bitfield is used.
+\end{alltt}
+
+Note, you must provide number of bits which is used to store the priority as
+the \uw{priobits} parameter. The section on prioritized execution describes how
+this bitfield is used.
 
-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.
+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} operator.  
+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 \CC{} \kw{delete} operator.  
 
 
 \subsection{Message Packing}
@@ -122,92 +112,100 @@ the programmer.  Messages can be deleted using the standard C++
 \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.
+When one declares \charmpp\ messages in the \texttt{.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.
+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
+\index{serialized messages}\index{message serialization}{\em only if} the
+message crosses the address-space boundary. This is provided in \charmpp\ using
 \kw{packed} messages.
 
 Such messages are declared in the {\tt .ci} file as:
 
-\verb+message [packed] PMessage;+
+\begin{alltt}
+message [packed] PMessage;
+\end{alltt}
 
-The class \uw{PMessage} needs to inherit from \uw{CMessage\_PMessage}
-and needs to provide two {\em static} methods: \kw{pack}
-and \kw{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:
+The class \uw{PMessage} needs to inherit from \uw{CMessage\_PMessage} and needs
+to provide two {\em static} methods: \kw{pack} and \kw{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}
+\begin{alltt}
 static void *PMessage::pack(PMessage *in);
 static PMessage *PMessage::unpack(void *in);
-\end{verbatim}
+\end{alltt}
 
 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} 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 Allocate buffer using the \kw{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:
+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 can be done using the in-place \kw{new} operator.}
+
 \item De-serialize message data from input buffer into the allocated message.
+
 \item Free the input buffer using \kw{CkFreeMsg}.
+
 \end{itemize}
 
-Here is an example of a {\em packed} message implementation:
+Here is an example of a \kw{packed} message implementation:
 
-\begin{verbatim}
+\begin{alltt}
 // File: pgm.ci
-mainmodule PackExample {
+mainmodule PackExample \{
   ...
   message [packed] PackedMessage;
   ...
-};
+\};
 
 // File: pgm.h
 ...
 class PackedMessage : public CMessage_PackedMessage
-{
+\{
   public:
     BinaryTree<char> btree; // Non-linear data structure used in e.g. only 
     static void* pack(PackedMessage*);
     static PackedMessage* unpack(void*);
     ...
-};
+\};
 ...
 
 // File: pgm.C
 ...
 void*
 PackedMessage::pack(PackedMessage* inmsg)
-{
+\{
   int treesize = inmsg->btree.getFlattenedSize();
   int totalsize = treesize + sizeof(int);
   char *buf = (char*)CkAllocBuffer(inmsg, totalsize);
@@ -220,11 +218,11 @@ PackedMessage::pack(PackedMessage* inmsg)
   buf = buf - sizeof(int);              // don't lose numnodes
   delete inmsg;
   return (void*) buf;
-}
+\}
 
 PackedMessage*
 PackedMessage::unpack(void* inbuf)
-{
+\{
   // inbuf is the raw memory allocated and assigned in pack
   char* buf = (char*) inbuf;
   int num_nodes;
@@ -239,19 +237,18 @@ PackedMessage::unpack(void* inbuf)
   pmsg = new ((void*)pmsg) PackedMessage(buf, num_nodes);  
   CkFreeMsg(inbuf);
   return pmsg;
-}
+\}
 ... 
 PackedMessage* pm = new PackedMessage();  // just like always 
 pm->btree.Insert('A');
 ...
-\end{verbatim}
+\end{alltt}
 
 
-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.
+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.
 
 
 \subsection{Variable Size Messages}
@@ -259,83 +256,91 @@ its member fields.
 \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} 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}
+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},
-\kw{unpack}, AND \kw{alloc} class methods.
+A \kw{varsize} message is declared as 
+
+\begin{alltt}
+  message [varsize] mtype;
+\end{alltt}
+
+in \charmpp\ interface file. The class \uw{mtype} has to inherit from
+\uw{CMessage\_mtype} AND has to provide \kw{pack}, \kw{unpack}, AND \kw{alloc}
+class methods.
 
 Thus, a varsize message is declared in the interface as: 
 
-\verb+message [varsize] VarsizeMessage;+ 
+\begin{alltt}
+message [varsize] VarsizeMessage; 
+\end{alltt}
 
 In the \CC\ header file, it has to be declared as: 
 
-\begin{verbatim}
-class VarsizeMessage : public CMessage_VarsizeMessage { 
+\begin{alltt}
+class VarsizeMessage : public CMessage_VarsizeMessage \
   public:
     // Other methods & data members 
     static void* alloc(int msgnum, size_t size, int* array, int priobits);
     static void* pack(VarsizeMessage*);
     static VarsizeMessage* unpack(void*);
-}; 
-\end{verbatim}
+\}; 
+\end{alltt}
 
-The \kw{alloc} method will be called when the message is allocated using
-the \CC\ \kw{new} operator. The programmer never needs to explicitly
-call it.  Note that all elements of the message are allocated when the message is created with \kw{new}.  There is no need to call \kw{new} to allocate any of the fields of the message.  This differs from a \kw{packed} message where each field requires individual allocation.     
-The \kw{alloc} method should actually allocate the message using
-\kw{CkAllocMsg}, whose signature is given below:
+The \kw{alloc} method will be called when the message is allocated using the
+\CC\ \kw{new} operator. The programmer never needs to explicitly call it.  Note
+that all elements of the message are allocated when the message is created with
+\kw{new}.  There is no need to call \kw{new} to allocate any of the fields of
+the message.  This differs from a \kw{packed} message where each field requires
+individual allocation.     The \kw{alloc} method should actually allocate the
+message using \kw{CkAllocMsg}, whose signature is given below:
 
-\begin{verbatim}
+\begin{alltt}
 void *CkAllocMsg(int msgnum, int size, int priobits); 
-\end{verbatim}  
+\end{alltt}  
 
-{\bf An Example:}
+\subsubsection{An Example}
 
 Suppose a \charmpp\ message contains two varsize fields:
 
-\begin{verbatim
-class VarsizeMessage: public CMessage_VarsizeMessage {
+\begin{alltt
+class VarsizeMessage: public CMessage_VarsizeMessage \{
   public:
     int lengthFirst;
     int lengthSecond;
     int* firstArray;
     double* secondArray;
     // other functions here
-};
-\end{verbatim}
+\};
+\end{alltt}
 
-Then in the {\tt .ci} file, this can be represented as: 
+Then in the \texttt{.ci} file, this can be represented as: 
 
-\begin{verbatim}
+\begin{alltt}
 message [varsize] VarsizeMessage;
-\end{verbatim}
+\end{alltt}
 
 and in the {\tt .h} or {\tt .C} file as:
 
-\begin{verbatim
+\begin{alltt
 
-class VarsizeMessage : public CMessage_VarsizeMessage { 
+class VarsizeMessage : public CMessage_VarsizeMessage \
   public: 
     int lengthFirst;
     int lengthSecond;
     int* firstArray;
     double* secondArray;
     // other functions here
-);
+\};
 
 // allocate memory for varmessage so charm can keep track of memory
 void* VarsizeMessage::alloc(int msgnum, size_t size, int* array, int priobits)
-{
+\{
   int totalsize, first_start, second_start;
   // array is passed in when the message is allocated using new (see below).
   // size is the amount of space needed for the part of the message known
@@ -357,26 +362,28 @@ void* VarsizeMessage::alloc(int msgnum, size_t size, int* array, int priobits)
   newMsg->secondArray = (double*) ((char*)newMsg + second_start);
 
   return (void*) newMsg;
-}
+\}
 
 // returns pointer to memory containing packed message
-void* VarsizeMessage::pack(VarsizeMessage* in) {
+void* VarsizeMessage::pack(VarsizeMessage* in)
+\{
   // set firstArray an offset from the start of in
   in->firstArray = (int*) ((char*)in->firstArray - (char*)in);
   // set secondArray to the appropriate offset
   in->secondArray = (double*) ((char*)in->secondArray - (char*)in);
   return in;
-}
+\}
 
 // returns new message from raw memory
-VarsizeMessage* VarsizeMessage::unpack(void* inbuf) {
+VarsizeMessage* VarsizeMessage::unpack(void* inbuf)
+\{
   VarsizeMessage* me = (VarsizeMessage*)inbuf;
   // return first array to absolute address in memory
   me->firstArray = (int*) ((size_t)me->firstArray + (char*)me);
   // likewise for secondArray
   me->secondArray = (double*) ((size_t)me->secondArray + (char*)me);
   return me;
-}
+\}
 
 int size[2];
 size[0] = 4;               // firstArray will have 4 elements
@@ -384,16 +391,12 @@ size[1] = 5;               // secondArray will have 5 elements
 VarsizeMessage* p = new(size, 0) VarsizeMessage;
 p->firstArray[2] = 13;     // the arrays have already been allocated 
 p->secondArray[4] = 6.7; 
+\end{alltt}
 
-
-
-\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. 
-
+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. 
 
 \subsection{Prioritized Execution}
 \label{prioritized message passing}
@@ -412,8 +415,7 @@ are processed is \kw{CkSetQueueing}.
 
 \function{void CkSetQueueing(MsgType message, int queueingtype)}
 
-where \uw{queueingtype} is one of the following
-constants:
+where \uw{queueingtype} is one of the following constants:
 
 \begin{alltt}
   CK_QUEUEING_FIFO
@@ -435,20 +437,19 @@ The first two options,  \kw{CK\_QUEUEING\_FIFO} and
   CkSetQueueing(msg2, CK_QUEUEING_LIFO);
 \end{alltt}
 
-When message \kw{msg1} arrives at its destination, it will be pushed
-onto the end of the message queue as usual.  However, when \kw{msg2}
-arrives, it will be pushed onto the {\em 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 this call:
+When message \kw{msg1} arrives at its destination, it will be pushed onto the
+end of the message queue as usual.  However, when \kw{msg2} arrives, it will be
+pushed onto the {\em 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 this call:
 
 \function{unsigned int *CkPriorityPtr(MsgType msg)}
 \index{CkPriorityPtr}
@@ -556,17 +557,17 @@ can strongly affect the efficiency of your program.
 \subsection{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:
+\charmpp{}  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 {\tt .ci} file
+declaration.  The syntax for this is as follows:
 
 \begin{alltt}
 entry [attribute1, ..., attributeN] void EntryMethod(MessageType *);
 \end{alltt}
 
-Charm++ currently offers four attributes that one may give an entry method:
+\charmpp{} currently offers four attributes that one may give an entry method:
 \kw{threaded}, \kw{sync}, \kw{exclusive}, and \kw{virtual}.
 
 \index{threaded}Threaded \index{entry method}entry methods are simply entry
@@ -591,18 +592,15 @@ method}entry method exclusive, add the keyword \kw{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
-\kw{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:
+same manner as virtual methods of sequential \CC{} objects.  For a detailed
+discussion of inheritance in \charmpp{}, refer to section \ref{inheritance and
+templates}.  To make an entry method virtual, just add the keyword \kw{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 \CC{} and are declared in a very
+similar fashion.  To make a virtual entry method pure, add a ``= 0'' after that
+entry method's {\tt .ci} file declaration.  This looks like the following:
 
 \begin{alltt}
 entry [virtual] void PureVirtualEntry(MessageType *) = 0;
 \end{alltt}
-
-
-
index 9d9e8b4b275362ad7c527547bd474917d58bc439..f2c75a2817f4540d105d9f442a032299020239ba 100644 (file)
@@ -2,16 +2,16 @@
 
 \subsection{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.
+A \charmpp\ program is structurally similar to a \CC{} program.  Most of a
+\charmpp\ program {\em is} \CC{} code \footnote{\bf Constraint: The \CC{} 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 Sequential objects: as in \CC{}
 \item Chares (concurrent objects) \index{chare}
 \item Chare Groups \index{chare groups} (a form of replicated objects)
 \index{group}
@@ -20,69 +20,68 @@ There are five disjoint categories of objects (classes) in \charmpp:
 \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 
-variables 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 has the suffix ``.ci''. 
-The \charmpp\ interface translator parses this file and produces two files 
-(with suffixes ``.decl.h'' and ``.def.h'', {\em for each modules declared in the ``.ci'' file}), 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.}.
+The user's code is written in \CC{} 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 \CC{} code that needs to be compiled with the user's code.
+
+Interfaces to the \charmpp\ objects (such as messages, chares, readonly
+variables 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 has the suffix ``.ci''.  The \charmpp\ interface
+translator parses this file and produces two files (with suffixes ``.decl.h''
+and ``.def.h'', {\em for each modules declared in the ``.ci'' file}), 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}
+\begin{alltt}
 ///////////////////////////////////////
 // File: pgm.ci
 
-mainmodule Hello {
+mainmodule Hello \{
   readonly CkChareID mid;
-  mainchare HelloMain {
+  mainchare HelloMain \{
     entry HelloMain(); // implicit CkArgMsg * as argument
     entry void Wait(void);
-  };
-  group HelloGroup {
+  \};
+  group HelloGroup \{
     entry HelloGroup(void);
-  };
-};
+  \};
+\};
 
 ////////////////////////////////////////
 // File: pgm.h
 #include "Hello.decl.h" // Note: not pgm.decl.h
 
-class HelloMain: public Chare {
+class HelloMain: public Chare \{
   public:
     HelloMain(CkArgMsg *);
     void Wait(void);
   private:
     int count;
-};
+\};
 
-class HelloGroup: public Group {
+class HelloGroup: public Group \{
   public:
     HelloGroup(void);
-};
+\};
 
 /////////////////////////////////////////
 // File: pgm.C
@@ -90,25 +89,25 @@ class HelloGroup: public Group {
 
 CkChareID mid;
 
-HelloMain::HelloMain(CkArgMsg *msg) {
+HelloMain::HelloMain(CkArgMsg *msg) \{
   delete msg;
   count = 0;
   CProxy_HelloGroup::ckNew(); // Create a new "HelloGroup"
   mid = thishandle;
-}
+\}
 
-void HelloMain::Wait(void) {
+void HelloMain::Wait(void) \{
   count++;
-  if (count == CkNumPes()) { // Wait for all group members to finish the printf
+  if (count == CkNumPes()) \{ // Wait for all group members to finish the printf
     CkExit();
-  }
-}
+  \}
+\}
 
-HelloGroup::HelloGroup(void) {
+HelloGroup::HelloGroup(void) \{
   ckout << "Hello World from processor " << CkMyPe() << endl;
   CProxy_HelloMain pself(mid);
   pself.Wait();
-}
+\}
 
 #include "Hello.def.h" // Include the Charm++ object implementations
 
@@ -120,35 +119,39 @@ pgm: pgm.ci pgm.h pgm.C
       charmc -c pgm.C
       charmc -o pgm pgm.o -language charm++
 
-\end{verbatim}
+\end{alltt}
 
-\uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm Kernel starts 
-execution of this program by creating an instance of \uw{HelloMain} on 
+\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 stores a handle to itself and returns. The call to create the 
-group returns 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, and call its constructor. The constructor 
-will then print 
-``Hello World...'' and then call the \uw{Wait} method 
-of \uw{HelloMain}. The Wait method calls CkExit() after all group members have called it (i.e., they have finished printing ``Hello World...''), and the \charmpp program exits.
+and stores a handle to itself and returns. The call to create the group returns
+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, and call its constructor. The constructor
+will then print ``Hello World...'' and then call the \uw{Wait} method of
+\uw{HelloMain}. The Wait method calls CkExit() after all group members have
+called it (i.e., they have finished printing ``Hello World...''), and the
+\charmpp program exits.
 
 \subsection{Functions in the ``decl.h'' and ``def.h'' files}
 
-       The \uw{decl.h} file provides declarations for the proxy classes of the concurrent objects declared in the ``.ci'' file (from which the \uw{decl.h} file is generated). So the \uw{Hello.decl.h} file will have the declaration of the class CProxy\_HelloMain. Similarly it will also have the declaration for the HelloGroup class. 
-
-       This class will have functions to create new instances of the chares and groups, like the function ckNew. For HelloGroup this function creates an instance of the class HelloGroup on all the processors. 
-
-       The proxy class also has functions corresponding to the entry methods defined in the ``.ci'' file. In the above program the method wait is declared in CProxy\_HelloMain (proxy class for HelloMain).
-
-       The proxy class also provides static registration functions used by the \charmpp runtime.  The \uw{def.h} file has a registration function (\_\_registerHello in the above program) which calls all the registration functions corresponding to the readonly variables and entry methods declared in the module.
-
-
-       
-
-
-
-
-
+The \texttt{decl.h} file provides declarations for the proxy classes of the
+concurrent objects declared in the ``.ci'' file (from which the \texttt{decl.h}
+file is generated). So the \uw{Hello.decl.h} file will have the declaration of
+the class CProxy\_HelloMain. Similarly it will also have the declaration for
+the HelloGroup class. 
+
+This class will have functions to create new instances of the chares and
+groups, like the function \kw{ckNew}. For \uw{HelloGroup} this function creates
+an instance of the class \uw{HelloGroup} on all the processors. 
+
+The proxy class also has functions corresponding to the entry methods defined
+in the ``.ci'' file. In the above program the method wait is declared in
+\uw{CProxy\_HelloMain} (proxy class for \uw{HelloMain}).
+
+The proxy class also provides static registration functions used by the
+\charmpp{} runtime.  The \texttt{def.h} file has a registration function
+(\uw{\_\_registerHello} in the above program) which calls all the registration
+functions corresponding to the readonly variables and entry methods declared in
+the module.
 
index a86751aab2813a251dba85ceb46c1b32dcb6a3bc..f37b90acd4bdb1652ca969287a13634cbf34e16f 100644 (file)
@@ -1,63 +1,55 @@
 \section{Nodegroup Objects}
 
-{\it Node groups} \index{node groups} \index{nodegroup} are very
+{\it Node groups}\experimental{} \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.
+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:
+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}
+\begin{alltt}
+ nodegroup NodegroupType \{
+  // Interface specifications as for normal chares
+ \};
+\end{alltt}
 
 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}
+\begin{alltt}
+ class NodeGroupType : public Nodegroup [,other superclasses ] \{
+  // Data and member functions as in \CC{}
+  // Entry functions as for normal chares
+ \};
+\end{alltt}
 
-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.
+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}\kw{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}.
+Node groups may possess \index{exclusive}\kw{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).
+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
@@ -66,17 +58,16 @@ branches.
 
 \subsection{Method Invocation on Nodegroups}
 
-Methods can be invoked either on a particular \index{branch}branch
-of a \index{nodegroup}nodegroup by specifying a {\em node number} as a method
+Methods can 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
+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
@@ -85,17 +76,15 @@ node may execute any other {\em exclusive} method of that
 execute other {\em non-exclusive} methods of that nodegroup
 \index{branch}branch, however.
 
-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.)
+The local \index{branch}branch of a \kw{nodegroup} can be accessed using
+\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.)
 
-\index{CkLocalNodeBranch}\kw{CkLocalNodeBranch} returns a generic
-({\tt void *}) pointer, similar to \kw{CkLocalBranch}.  Also, the static
-method \kw{ckLocalNodeBranch} of the proxy class of appropriate
-\index{nodegroup}nodegroup can be called to get the correct type of
-pointer.
+\kw{CkLocalNodeBranch} returns a generic ({\tt void *}) pointer, similar to
+\kw{CkLocalBranch}.  Also, the static method \kw{ckLocalNodeBranch} of the
+proxy class of appropriate \index{nodegroup}nodegroup can be called to get the
+correct type of pointer.
index ccfb27a70af2a9461d43cb5cca65c6d92c1b002f..7eee614ba153b34483906ced0716b2fbcc0d99e8 100644 (file)
@@ -13,51 +13,51 @@ Thus if a parallel program is executing on one 4-processor workstation and one
 and 5) but only 2 nodes (0 and 1).  A given node's processing elements are
 numbered sequentially.
 
-\function{int CkNumPes()} \index{CkNumPes} \\
+\function{int CkNumPes()} \index{CkNumPes}
 \desc{returns the total number of processors, across all nodes.}
 
-\function{int CkMyPe()} \index{CkMyPe} \\
+\function{int CkMyPe()} \index{CkMyPe}
 \desc{returns the processor number on which the call was made.}
 
-\function{int CkMyRank()} \index{CkMyRank} \\
+\function{int CkMyRank()} \index{CkMyRank}
 \desc{returns the rank number of the processor on which the call was made.
 Processing elements within a node are ranked starting from zero.}
 
-\function{int CkMyNode()} \index{CkMyNode} \\
+\function{int CkMyNode()} \index{CkMyNode}
 \desc{returns the address space number (node number) on which the call was made.}
 
-\function{int CkNumNodes()} \index{CkMyNodes} \\
+\function{int CkNumNodes()} \index{CkMyNodes}
 \desc{returns the total number of address spaces.}
 
-\function{int CkNodeFirst(int node)} \index{CkNodeFirst} \\
+\function{int CkNodeFirst(int node)} \index{CkNodeFirst}
 \desc{returns the processor number of the first processor in this address space.}
 
-\function{int CkNodeSize(int node)} \index{CkNodeSize} \\
+\function{int CkNodeSize(int node)} \index{CkNodeSize}
 \desc{returns the number of processors in the address space on which the call was made.}
 
-\function{int CkNodeOf(int pe)} \index{CkNodeOf} \\
+\function{int CkNodeOf(int pe)} \index{CkNodeOf}
 \desc{returns the node number on which the call was made.}
 
-\function{int CkRankOf(int pe)} \index{CkRankOf} \\
+\function{int CkRankOf(int pe)} \index{CkRankOf}
 \desc{returns the rank of the given processor within its node.}
 
 The following calls provide commonly needed functions.
 
-\function{void CkAbort(const char *message)} \index{CkAbort} \\
+\function{void CkAbort(const char *message)} \index{CkAbort}
 \desc{Cause the program to abort, printing the given error message.}
 
-\function{void CkExit()} \index{CkExit} \\
-\desc{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.  \kw{CkExit()}
-should be the last statement of the entry method from which it was
-called.}
+\function{void CkExit()} \index{CkExit}
+\desc{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.  \kw{CkExit} should be the last
+call of the entry method from which it was called.}
 
-\function{double CkTimer()} \index{CkTimer} \index{timers} \\
+\function{double CkTimer()} \index{CkTimer} \index{timers}
 \desc{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).}
+timer is started when the program begins execution. This timer measures process
+time (user and system).}
 
-\function{double CkWallTimer()} \index{CkWallTimer} \index{timers} \\
-\desc{returns the elapsed time since the program has started from the wall clock timer.}
+\function{double CkWallTimer()} \index{CkWallTimer} \index{timers}
+\desc{returns the elapsed time since the program has started from the wall
+clock timer.}
 
index 9e9935cfde8f990e6ef53d20ce113bd9424dc511..32f548a9342d9913a7c4f029c9ebcc3f49513552 100644 (file)
@@ -1,4 +1,4 @@
-\chapter{Charm++ Overview}
+\chapter{\charmpp{} Overview}
 
 We think that \charmpp\ is easy to use if you are familiar with object-based
 programming. (But of course that is our opinion, if your opinion differs, you
@@ -12,10 +12,12 @@ the object, and only the methods of that class can manipulate that data. A
 method that has the same name as the class is a ``blessed'' method, called a
 ``Constructor'' for that class.  Constructor method is typically responsible
 for initializing the encapsulated data of an object. Each method, including the
-constructor can optionally be
-supplied data in the form of parameters (or arguments). In \CC, one can create objects with the {\tt new} operator that returns a pointer to the object. This pointer can be used to refer to the object, and call methods on that object.
+constructor can optionally be supplied data in the form of parameters (or
+arguments). In \CC, one can create objects with the {\tt new} operator that
+returns a pointer to the object. This pointer can be used to refer to the
+object, and call methods on that object.
 
-\charmpp is built on top of \CC, and also based on ``encapsulation''. Similar
+\charmpp{} is built on top of \CC, and also based on ``encapsulation''. Similar
 to \CC, \charmpp\ entities can contain private data, and public methods. The
 major difference is that these methods can be invoked from remote processors
 asynchronously.  Asynchronous method invocation implies that the caller does
@@ -92,12 +94,12 @@ 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, 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.
+only one instance of this, 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
@@ -121,15 +123,14 @@ allow entry methods to be executed in separate user-level threads.  These
 making {\em synchronous} calls to remote object methods that return results in
 messages.
 
-\charmpp\ program execution is terminated by the 
-\kw{CkExit} call. This call is not the same as 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 \kw{CkExit} is called.
-Charm Kernel ensures that no messages are processed and no entry methods are
-called after the currently executing entry method completes. \kw{CkExit}
-need not be called on all processors; it is enough to call it from just one
-processor at the end of the computation.
+\charmpp\ program execution is terminated by the \kw{CkExit} call. This call is
+not the same as 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 \kw{CkExit} is called.  Charm Kernel ensures that no messages are
+processed and no entry methods are called after the currently executing entry
+method completes. \kw{CkExit} need not be called on all processors; it is
+enough to call it from just one processor at the end of the computation.
 
 \section{Entities in \charmpp\ programs}
 
@@ -138,17 +139,17 @@ This section describes various entities in a typical \charmpp\ program.
 \subsection{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
+objects are similar to the objects in \CC, 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
+presence of global or static variables.}. These objects are created
+synchronously on the local processor (using a {\tt new} operator in \CC), and
 their methods 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.
+These objects are not known to the \charmpp\ runtime system, and thus they need
+not be mentioned in the module interface files.
 
 \subsection{Messages}
 
@@ -160,9 +161,9 @@ special class that is generated by the \charmpp\ interface translator.  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: \kw{pack}, and \kw{unpack}.
-These messages are specified differently in the interface file for the module.
-The third variation of communication objects is called {\em varsize} messages.
+communication objects contains two methods: \kw{pack}, and \kw{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.
@@ -172,9 +173,9 @@ the interface file.
 Chares are the most important entities in a \charmpp\ program. These concurrent
 objects are different from sequential \CC\ objects in many ways. Syntactically,
 Chares are instances of \CC\  classes that are derived from a system-provided
-class called \kw{Chare}. Also, in addition to the usual \CC\ 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}
+class called \kw{Chare}. Also, in addition to the usual \CC\ 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 at most one argument, which is a pointer to a message.
 Chares are {\em accessed} using a proxy (an object of a specialized class
 generated by the \charmpp\ interface translator) or using a handle (a \kw{
@@ -190,16 +191,16 @@ interface file.
 \subsection{Chare Groups}
 
 Chare Groups\footnote{ These were called Branch Office Chares (BOC) in earlier
-version of Charm.  } are a special type of concurrent objects.  Each chare
-group is a collection of chares, with one representative (group member) on each
+version of Charm.} are a special type of concurrent objects.  Each chare group
+is a collection of chares, with one representative (group member) on each
 processor. All the members of a chare group share a globally unique name
-(handle, defined by Charm kernel to be of type \kw{CkGroupID}). An entire
-chare group could be addressed using this global handle, and an individual
-member of a chare group can be addressed using the global handle, and a
-processor number. Chare groups are instances of \CC\ classes subclassed from a
-system-provided class called \kw{Group}. The Charm kernel has to be notified
-that these chares are semantically different, and therefore chare groups have a
-different declaration in the interface specification file.
+(handle, defined by Charm kernel to be of type \kw{CkGroupID}). An entire chare
+group could be addressed using this global handle, and an individual member of
+a chare group can be addressed using the global handle, and a processor number.
+Chare groups are instances of \CC\ classes subclassed from a system-provided
+class called \kw{Group}. The Charm kernel has to be notified that these chares
+are semantically different, and therefore chare groups have a different
+declaration in the interface specification file.
 
 \subsection{Chare Nodegroups}
 
index 3dcdc8a287b81549fba0fe61249d756854d8eac9..b1becb3678fee90e8b251d140987b68edf1482d1 100644 (file)
@@ -12,52 +12,47 @@ 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}
+\begin{alltt}
+ CkStartQd(int Index, 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
-\kw{CProxy} object corresponding to the \index{chare}chare
-containing that entry method.  The syntax of this call is as follows:
+method, you must use a static method contained within the \uw{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}
+\begin{alltt}
+CProxy_ChareName::ckIdx_EntryMethod(Msg *Message);
+\end{alltt}
 
-where {\it chareID} is the name of the chare identifier of the chare containing
+where \uw{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
+and \uw{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} 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:
+of this convoluted looking static method call.  \kw{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}
+\begin{alltt}
+ EntryIndex(ChareName, EntryName, MsgName);
+\end{alltt}
 
-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).
+Note that \uw{ChareName}, \uw{EntryName}, and \uw{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).
 
 \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}
+\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
index 9e70fb60a3e613fdee80ca49aaa82f82e0634ad1..e602b9941b44223877248aee2cd7e5f7e900d39a 100644 (file)
@@ -1,71 +1,59 @@
 \section{Read-only Variables, Messages and Arrays}
 
-Since \charmpp\ does not allow global variables for keeping
-programs portable across a wide range of machines, 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 dynamic scope of 
-{\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}. 
+Since \charmpp\ does not allow global variables for keeping programs portable
+across a wide range of machines, 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 dynamic scope
+of {\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 \kw{readonly}, which is similar to \kw{const} in
-\CC. Read-only data is specified in the {\tt .ci} file (the interface
-file) as: 
+modifier \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}
+\begin{alltt}
+ readonly Type ReadonlyVarName;
+\end{alltt}
 
-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.
+The variable \uw{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}
+\begin{alltt}
+ readonly MessageType *ReadonlyMsgName;
+\end{alltt}
 
-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.
+The variable \uw{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}
+\begin{alltt}
+ readonly Type ReadonlyArrayName [arraysize];
+\end{alltt}
 
-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.
+The variable \uw{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}
+\begin{alltt}
+ Type ReadonlyVarName;
+ MessageType *ReadonlyMsgName;
+ Type ReadonlyArrayName [arraysize];
+\end{alltt}
 
 Similar declarations preceded by \kw{extern} would appear in the {\tt
 .h} file. 
 
-{\it Note:}  The current \charmpp\ compiler cannot prevent
+{\it Note:}  The current \charmpp\ translator cannot prevent
 assignments to read-only variables.  The user must make sure that no
 assignments occur in the program.
 
-
-
-
index c400193e7431f82e46316cc86848ae570beb510f..3b796eafdc84bf4a859f013fffebd45262eaa953 100644 (file)
@@ -1,62 +1,42 @@
 \chapter{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.
+\charmpp\ is based on the Message-Driven parallel programming paradigm.  The
+message-drivern 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{figure}[ht]
 \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}
-}
+\begin{alltt}
+      class compute_object : public 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{alltt}
 \end{center}
 \caption{Compute Object in a Molecular Dynamics Application}
 \label{figchareexample}
@@ -101,128 +81,105 @@ 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{figure}[ht]
 \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}
-}
+\begin{alltt}
+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{alltt}
 \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 \uw{getFirst}, 
-and \uw{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, \uw{recvFirst} and \uw{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}
+Contrast the compute chare-object example in figure~\ref{figchareexample} with
+a thread-based implementation of the same scheme in
+figure~\ref{figthreadexample}. Functions \uw{getFirst}, and \uw{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, \uw{recvFirst} and
+\uw{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}[ht]
 \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}
-}
+\begin{alltt}
+  class compute_object
+    sdagentry compute_object(MSG *msg)\{
+      atomic \{
+         PatchManager->Get(msg->first_index,\dots);
+         PatchManager->Get(msg->second_index,\dots);
+      \}
+      overlap \{
+        when recv_first(Patch *first) atomic \{ filter(first); \}
+        when recv_second(Patch *second) atomic \{ filter(second); \}
+      \}
+      atomic \{ computeInteractions(first, second); \}
+    \}
+  \}
+\end{alltt}
 \end{center}
 \caption{\sdag\ Implementation of the Compute Object}
 \label{figsdagexample}
 \end{figure}
 
-\sdag\ 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.
+\sdag\ 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.
 
 \section{Grammar}
 
 \subsection{Tokens}
 
-\begin{verbatim}
-  <ident> = Valid C++ identifier 
-  <int-expr> = Valid C++ integer expression 
-  <c++-code> = Valid C++ code 
-\end{verbatim}
+\begin{alltt}
+  <ident> = Valid \CC{} identifier 
+  <int-expr> = Valid \CC{} integer expression 
+  <\CC{}-code> = Valid \CC{} code 
+\end{alltt}
 
 \subsection{Grammar in EBNF Form}
 
-\begin{verbatim}
+\begin{alltt}
 <sdag> := <class-decl> <sdagentry>+ 
 
 <class-decl> := "class" <ident> 
@@ -230,7 +187,7 @@ language. Grammar of \sdag\ is given in the EBNF form below.
 <sdagentry> := "sdagentry" <ident> "(" <ident> "*" <ident> ")" <body> 
 
 <body> := <stmt> 
-        | "{" <stmt>+ "}" 
+        | "\{" <stmt>+ "\}" 
 
 <stmt> := <overlap-stmt> 
         | <when-stmt> 
@@ -242,7 +199,7 @@ language. Grammar of \sdag\ is given in the EBNF form below.
 
 <overlap-stmt> := "overlap" <body> 
 
-<atomic-stmt> := "atomic" "{" <c++-code> "}" 
+<atomic-stmt> := "atomic" "\{" <\CC-code> "\}" 
 
 <if-stmt> := "if" "(" <int-expr> ")" <body> [<else-stmt>] 
 
@@ -263,11 +220,9 @@ language. Grammar of \sdag\ is given in the EBNF form below.
 
 <entry> := <ident> [ "[" <int-expr> "]" ] "(" <ident> "*" <ident> ")" 
   
-\end{verbatim}
+\end{alltt}
 
 
 For more details regarding \sdag, look at the examples located in
 {\tt pgms/sdag} directory in the \charmpp\ distribution.
 
-
-
index a585e924fce9fbe7fc48d3c04635079445cc2abd..cb7f03e099aeb54deb306d5cb8c64ddfd36c668e 100644 (file)
@@ -1,6 +1,6 @@
 \section{Sequential Objects}
 \index{sequential objects} 
 
-These are the same as C++ classes and functions.  All C++ features can
+These are the same as \CC{} classes and functions.  All \CC{} features can
 be used.  However, care needs to be taken when sequential objects
 interact with \charmpp\ objects.
index fc002cb12cd4e7eead95d443e308d536d5c02504..726ff1c299fd29d4628fa4c122b17c82e15422c8 100644 (file)
@@ -12,6 +12,7 @@
 \newcommand{\ampi}{\textsc{AMPI}}
 \newcommand{\tempo}{\textsc{TeMPO}}
 \newcommand{\irecv}{\textsl{iRecv}}
+\newcommand{\sdag}{\textsl{Structured Dagger}}
 
 %%% Commands to produce margin symbols
 \newcommand{\new}{\marginpar{\fbox{\bf$\mathcal{NEW}$}}}