Charm++ manual reorganization
authorLukasz Wesolowski <wesolwsk@illinois.edu>
Mon, 23 Jul 2012 18:43:30 +0000 (13:43 -0500)
committerLukasz Wesolowski <wesolwsk@illinois.edu>
Mon, 23 Jul 2012 18:43:30 +0000 (13:43 -0500)
18 files changed:
doc/charm++/advancedarrays.tex [new file with mode: 0644]
doc/charm++/advancedlb.tex
doc/charm++/advancedpup.tex [new file with mode: 0644]
doc/charm++/arrays.tex
doc/charm++/credits.tex [new file with mode: 0644]
doc/charm++/entry.tex
doc/charm++/intro.tex
doc/charm++/loadb.tex
doc/charm++/manual.tex
doc/charm++/marshalling.tex
doc/charm++/modules.tex
doc/charm++/overview.tex
doc/charm++/pup.tex
doc/charm++/reductions.tex
doc/charm++/sdag.tex
doc/libraries/liveviz.tex
doc/pplmanual.sty
doc/projections/manual.tex

diff --git a/doc/charm++/advancedarrays.tex b/doc/charm++/advancedarrays.tex
new file mode 100644 (file)
index 0000000..e73687c
--- /dev/null
@@ -0,0 +1,866 @@
+\subsection{Advanced Arrays}
+
+\label{advanced arrays}
+
+The basic array features described before (creation, messaging,
+broadcasts, and reductions) are needed in almost every
+\charmpp{} program.  The more advanced techniques that follow
+are not universally needed; but are still often useful.
+
+\subsubsection{Local Access}
+
+\experimental{}
+\index{ckLocal for arrays}
+\label{ckLocal for arrays}
+You can get direct access to a local array element using the
+proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
+to the element if it exists on the local processor; and NULL if
+the element does not exist or is on another processor.
+
+\begin{alltt}
+A1 *a=a1[i].ckLocal();
+if (a==NULL) //...is remote-- send message
+else //...is local-- directly use members and methods of a
+\end{alltt}
+
+Note that if the element migrates or is deleted, any pointers 
+obtained with \kw{ckLocal} are no longer valid.  It is best,
+then, to either avoid \kw{ckLocal} or else call \kw{ckLocal} 
+each time the element may have migrated; e.g., at the start 
+of each entry method.
+
+\subsubsection{Advanced Array Creation}
+
+\label{advanced array create}
+There are several ways to control the array creation process.
+You can adjust the map and bindings before creation, change
+the way the initial array elements are created, create elements
+explicitly during the computation, and create elements implicitly,
+``on demand''.  
+
+You can create all your elements using any one of these methods,
+or create different elements using different methods.  
+An array element has the same syntax and semantics no matter
+how it was created.
+
+\subsubsection{Advanced Array Creation: CkArrayOptions}
+
+\index{CkArrayOptions}
+\label{CkArrayOptions}
+
+The array creation method \kw{ckNew} actually takes a parameter
+of type \kw{CkArrayOptions}.  This object describes several
+optional attributes of the new array.
+
+The most common form of \kw{CkArrayOptions} is to set the number
+of initial array elements.  A \kw{CkArrayOptions} object will be 
+constructed automatically in this special common case.  Thus
+the following code segments all do exactly the same thing:
+
+\begin{alltt}
+//Implicit CkArrayOptions
+  a1=CProxy_A1::ckNew(\uw{parameters},nElements);
+
+//Explicit CkArrayOptions
+  a1=CProxy_A1::ckNew(\uw{parameters},CkArrayOptions(nElements));
+
+//Separate CkArrayOptions
+  CkArrayOptions opts(nElements);
+  a1=CProxy_A1::ckNew(\uw{parameters},opts);
+\end{alltt}
+
+Note that the ``numElements'' in an array element is simply the
+numElements passed in when the array was created.  The true number of
+array elements may grow or shrink during the course of the
+computation, so numElements can become out of date.  This ``bulk''
+constructor approach should be preferred where possible, especially
+for large arrays.  Bulk construction is handled via a broadcast which
+will be significantly more efficient in the number of messages
+required than inserting each element individually which will require
+one message send per element.
+
+\kw{CkArrayOptions} contains a few flags that the runtime can use to
+optimize handling of a given array. If the array elements will only
+migrate at controlled points (such as periodic load balancing with
+{\tt AtASync()}), this is signalled to the runtime by calling {\tt
+  opts.setAnytimeMigration(false)}\footnote{At present, this optimizes
+broadcasts to not save old messages for immigrating chares.}. If all
+array elements will be inserted by bulk creation or by {\tt
+  fooArray[x].insert()} calls, signal this by calling {\tt
+  opts.setStaticInsertion(true)} \footnote{This can enable a slightly
+  faster default mapping scheme.}.
+
+\subsubsection{Advanced Array Creation: Map Object}
+
+\index{array map}
+\label{array map}
+
+You can use \kw{CkArrayOptions} to specify a ``map object''
+for an array.  The map object is used by the array manager
+to determine the ``home'' processor of each element.  The
+home processor is the processor responsible for maintaining
+the location of the element.
+
+There is a default map object, which maps 1D array indices
+in a block fashion to processors, and maps other array
+indices based on a hash function. Some other mappings such as round-robin
+(\kw{RRMap}) also exist, which can be used
+similar to custom ones described below.
+
+A custom map object is implemented as a group which inherits from
+\kw{CkArrayMap} and defines these virtual methods:
+
+\begin{alltt}
+class CkArrayMap : public Group
+\{
+public:
+  //...
+  
+  //Return an ``arrayHdl'', given some information about the array
+  virtual int registerArray(CkArrayIndex& numElements,CkArrayID aid);
+  //Return the home processor number for this element of this array
+  virtual int procNum(int arrayHdl,const CkArrayIndex &element);
+\}
+\end{alltt}
+
+For example, a simple 1D blockmapping scheme.  Actual mapping is
+handled in the procNum function.
+
+\begin{alltt}
+class BlockMap : public CkArrayMap 
+\{
+ public:
+  BlockMap(void) \{\}
+  BlockMap(CkMigrateMessage *m)\{\}
+  int registerArray(CkArrayIndex& numElements,CkArrayID aid) \{
+    return 0;
+  \}
+  int procNum(int /*arrayHdl*/,const CkArrayIndex &idx) \{
+    int elem=*(int *)idx.data();
+    int penum =  (elem/(32/CkNumPes()));
+    return penum;
+  \}
+\};
+
+\end{alltt}
+Once you've instantiated a custom map object, you can use it to
+control the location of a new array's elements using the
+\kw{setMap} method of the \kw{CkArrayOptions} object described above.
+For example, if you've declared a map object named ``BlockMap'':
+
+\begin{alltt}
+//Create the map group
+  CProxy_BlockMap myMap=CProxy_BlockMap::ckNew();
+//Make a new array using that map
+  CkArrayOptions opts(nElements);
+  opts.setMap(myMap);
+  a1=CProxy_A1::ckNew(\uw{parameters},opts);
+\end{alltt}
+
+
+
+\subsubsection{Advanced Array Creation: Initial Elements}
+
+\index{array initial}
+\label{array initial}
+
+The map object described above can also be used to create
+the initial set of array elements in a distributed fashion.
+An array's initial elements are created by its map object,
+by making a call to \kw{populateInitial} on each processor.
+
+You can create your own set of elements by creating your
+own map object and overriding this virtual function of \kw{CkArrayMap}:
+
+\begin{alltt}
+  virtual void populateInitial(int arrayHdl,int numInitial,
+       void *msg,CkArrMgr *mgr)
+\end{alltt}
+
+In this call, \kw{arrayHdl} is the value returned by \kw{registerArray},
+\kw{numInitial} is the number of elements passed to \kw{CkArrayOptions},
+\kw{msg} is the constructor message to pass, and \kw{mgr} is the
+array to create.
+
+\kw{populateInitial} creates new array elements using the method
+\kw{void CkArrMgr::insertInitial(CkArrayIndex idx,void *ctorMsg)}.
+For example, to create one row of 2D array elements on each processor,
+you would write:
+
+\begin{alltt}
+void xyElementMap::populateInitial(int arrayHdl,int numInitial,
+       void *msg,CkArrMgr *mgr)
+\{
+  if (numInitial==0) return; //No initial elements requested
+       
+  //Create each local element
+  int y=CkMyPe();
+  for (int x=0;x<numInitial;x++) \{
+    mgr->insertInitial(CkArrayIndex2D(x,y),CkCopyMsg(&msg));
+  \}
+  mgr->doneInserting();
+  CkFreeMsg(msg);
+\}
+\end{alltt}
+
+Thus calling \kw{ckNew(10)} on a 3-processor machine would result in
+30 elements being created.
+
+
+\subsubsection{Advanced Array Creation: Bound Arrays}
+
+\experimental{}
+\index{bound arrays} \index{bindTo}
+\label{bound arrays}
+You can ``bind'' a new array to an existing array
+using the \kw{bindTo} method of \kw{CkArrayOptions}.  Bound arrays
+act like separate arrays in all ways except for migration--
+corresponding elements of bound arrays always migrate together.
+For example, this code creates two arrays A and B which are
+bound together-- A[i] and B[i] will always be on the same processor.
+
+\begin{alltt}
+//Create the first array normally
+  aProxy=CProxy_A::ckNew(\uw{parameters},nElements);
+//Create the second array bound to the first
+  CkArrayOptions opts(nElements);
+  opts.bindTo(aProxy);
+  bProxy=CProxy_B::ckNew(\uw{parameters},opts);
+\end{alltt}
+
+An arbitrary number of arrays can be bound together--
+in the example above, we could create yet another array
+C and bind it to A or B.  The result would be the same
+in either case-- A[i], B[i], and C[i] will always be
+on the same processor.
+
+There is no relationship between the types of bound arrays--
+it is permissible to bind arrays of different types or of the
+same type.  It is also permissible to have different numbers
+of elements in the arrays, although elements of A which have
+no corresponding element in B obey no special semantics.
+Any method may be used to create the elements of any bound
+array.
+
+Bound arrays are often useful if A[i] and B[i] perform different 
+aspects of the same computation, and thus will run most efficiently 
+if they lie on the same processor.  Bound array elements are guaranteed
+to always be able to interact using \kw{ckLocal} (see 
+section~\ref{ckLocal for arrays}), although the local pointer must
+be refreshed after any migration. This should be done during the \kw{pup}
+routine. When migrated, all elements that are bound together will be created
+at the new processor before \kw{pup} is called on any of them, ensuring that
+a valid local pointer to any of the bound objects can be obtained during the
+\kw{pup} routine of any of the others.
+
+For example, an array {\it Alibrary} is implemented as a library module.
+It implements a certain functionality by operating on a data array {\it dest}
+which is just a pointer to some user provided data.
+A user defined array {\it UserArray} is created and bound to 
+the array {\it Alibrary} to take advanatage of the functionality provided 
+by the library.
+When bound array element migrated, the {\it data} pointer in {\it UserArray}
+is re-allocated in {\it pup()}, thus {\it UserArray} is responsible to refresh
+the pointer {\it dest} stored in {\it Alibrary}.
+
+\begin{alltt}
+class Alibrary: public CProxy_Alibrary \{
+public:
+  ...
+  void set_ptr(double *ptr) \{ dest = ptr; \}
+  virtual void pup(PUP::er &p);
+private:
+  double *dest;           // point to user data in user defined bound array
+\};
+
+class UserArray: public CProxy_UserArray \{
+public:
+  virtual void pup(PUP::er &p) \{
+                p|len;
+                if(p.isUnpacking()) \{ 
+                  data = new double[len];
+                  Alibrary *myfellow = AlibraryProxy(thisIndex).ckLocal();
+                  myfellow->set_ptr(data);    // refresh data in bound array
+                \}
+                p(data, len);
+  \}
+private:
+  CProxy_Alibrary  AlibraryProxy;   // proxy to my bound array
+  double *data;          // user allocated data pointer
+  int len;
+\};
+\end{alltt}
+
+
+\subsubsection{Advanced Array Creation: Dynamic Insertion}
+
+\label{dynamic_insertion}
+
+In addition to creating initial array elements using ckNew,
+you can also
+create array elements during the computation.
+
+You insert elements into the array by indexing the proxy
+and calling insert.  The insert call optionally takes 
+parameters, which are passed to the constructor; and a
+processor number, where the element will be created.
+Array elements can be inserted in any order from 
+any processor at any time.  Array elements need not 
+be contiguous.
+
+If using \kw{insert} to create all the elements of the array,
+you must call \kw{CProxy\_Array::doneInserting} before using
+the array.
+
+\begin{alltt}
+//In the .C file:
+int x,y,z;
+CProxy_A1 a1=CProxy_A1::ckNew();  //Creates a new, empty 1D array
+for (x=...) \{
+   a1[x  ].insert(\uw{parameters});  //Bracket syntax
+   a1(x+1).insert(\uw{parameters});  // or equivalent parenthesis syntax
+\}
+a1.doneInserting();
+
+CProxy_A2 a2=CProxy_A2::ckNew();   //Creates 2D array
+for (x=...) for (y=...)
+   a2(x,y).insert(\uw{parameters});  //Can't use brackets!
+a2.doneInserting();
+
+CProxy_A3 a3=CProxy_A3::ckNew();   //Creates 3D array
+for (x=...) for (y=...) for (z=...)
+   a3(x,y,z).insert(\uw{parameters});
+a3.doneInserting();
+
+CProxy_AF aF=CProxy_AF::ckNew();   //Creates user-defined index array
+for (...) \{
+   aF[CkArrayIndexFoo(...)].insert(\uw{parameters}); //Use brackets...
+   aF(CkArrayIndexFoo(...)).insert(\uw{parameters}); //  ...or parenthesis
+\}
+aF.doneInserting();
+
+\end{alltt}
+
+The \kw{doneInserting} call starts the reduction manager (see ``Array
+Reductions'') and load balancer (see ~\ref{lbFramework})-- since
+these objects need to know about all the array's elements, they
+must be started after the initial elements are inserted.
+You may call \kw{doneInserting} multiple times, but only the first
+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.
+
+If you do not specify one, the system will choose a procesor to 
+create an array element on based on the current map object.
+
+
+
+\subsubsection{Advanced Array Creation: Demand Creation}
+
+Normally, invoking an entry method on a nonexistant array
+element is an error.  But if you add the attribute
+\index{createhere} \index{createhome}
+\kw{[createhere]} or \kw{[createhome]} to an entry method,
+ the array manager will 
+``demand create'' a new element to handle the message.  
+
+With \kw{[createhome]}, the new element
+will be created on the home processor, which is most efficient when messages for
+the element may arrive from anywhere in the machine. With \kw{[createhere]},
+the new element is created on the sending processor, which is most efficient
+if when messages will often be sent from that same processor.
+
+The new element is created by calling its default (taking no
+paramters) constructor, which must exist and be listed in the .ci file.
+A single array can have a mix of demand-creation and
+classic entry methods; and demand-created and normally 
+created elements.
+
+
+
+\subsubsection{User-defined array index type}
+
+\index{Array index type, user-defined}
+\charmpp{} array indices are arbitrary collections of integers.
+To define a new array index, you create an ordinary C++ class 
+which inherits from \kw{CkArrayIndex} and sets the ``nInts'' member
+to the length, in integers, of the array index.
+
+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{alltt}
+#include <charm++.h>
+class CkArrayIndexFoo:public CkArrayIndex \{
+    Foo f;
+public:
+    CkArrayIndexFoo(const Foo \&in) 
+    \{
+        f=in;
+        nInts=sizeof(f)/sizeof(int);
+    \}
+    //Not required, but convenient: cast-to-foo operators
+    operator Foo &() \{return f;\}
+    operator const Foo &() const \{return f;\}
+\};
+\end{alltt}
+
+Note that \uw{Foo}'s size must be an integral number of integers--
+you must pad it with zero bytes if this is not the case.
+Also, \uw{Foo} must be a simple class-- it cannot contain 
+pointers, have virtual functions, or require a destructor.
+Finally, there is a \charmpp\ configuration-time option called
+CK\_ARRAYINDEX\_MAXLEN \index{CK\_ARRAYINDEX\_MAXLEN} 
+which is the largest allowable number of 
+integers in an array index.  The default is 3; but you may 
+override this to any value by passing ``-DCK\_ARRAYINDEX\_MAXLEN=n'' 
+to the \charmpp\ build script as well as all user code. Larger 
+values will increase the size of each message.
+
+You can then declare an array indexed by \uw{Foo} objects with
+
+\begin{alltt}
+//in the .ci file:
+array [Foo] AF \{ entry AF(); ... \}
+
+//in the .h file:
+class AF : public CBase\_AF
+\{ public: AF() \{\} ... \}
+
+//in the .C file:
+    Foo f;
+    CProxy_AF a=CProxy_AF::ckNew();
+    a[CkArrayIndexFoo(f)].insert();
+    ...
+\end{alltt}
+
+Note that since our CkArrayIndexFoo constructor is not declared
+with the explicit keyword, we can equivalently write the last line as:
+
+\begin{alltt}
+    a[f].insert();
+\end{alltt}
+
+When you implement your array element class, as shown above you 
+can inherit from \kw{CBase}\_\uw{ClassName}, 
+a class templated by the index type \uw{Foo}. In the old syntax,
+you could also inherit directly from \kw{ArrayElementT}.
+The array index (an object of type \uw{Foo}) is then accessible as 
+``thisIndex''. For example:
+
+\begin{alltt}
+
+//in the .C file:
+AF::AF()
+\{
+    Foo myF=thisIndex;
+    functionTakingFoo(myF);
+\}
+\end{alltt}
+
+
+\subsubsection{Migratable Array Elements}
+
+\label{arraymigratable}
+Array objects can \index{migrate}migrate from one PE to another.
+For example, the load balancer (see section~\ref{lbFramework})
+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{alltt}
+//In the .h file:
+class A2 : public CBase\_A2 \{
+private: //My data members:
+    int nt;
+    unsigned char chr;
+    float flt[7];
+    int numDbl;
+    double *dbl;
+public:        
+    //...other declarations
+
+    virtual void pup(PUP::er \&p);
+\};
+
+//In the .C file:
+void A2::pup(PUP::er \&p)
+\{
+    CBase\_A2::pup(p); //<- MUST 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{alltt}
+
+Please note that if your object contains Structured Dagger code (see section ``Structured Dagger'') you must use the following syntax to correctly pup the object:
+
+\begin{alltt}
+class bar: public CBase\_bar \{
+ private:
+    int a,b;
+ public:
+    bar_SDAG_CODE 
+    ...other methods...
+
+    virtual void pup(PUP::er& p) \{
+      __sdag_pup(p);
+      ...pup other data here...
+    \}
+\};
+\end{alltt}
+
+See the \index{PUP} section ``PUP'' for more details on pup routines
+and the \kw{PUP::er} type.
+
+The system uses one pup routine to do both packing and unpacking by
+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 \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 section~\ref{lbarray}).
+
+To migrate your array element to another processor, the \charmpp{}
+runtime will:
+
+\begin{itemize}
+\item Call your \kw{ckAboutToMigrate} method
+\item Call your \uw{pup} method with a sizing \kw{PUP::er} to determine how 
+big a message it needs to hold your element.
+\item Call your \uw{pup} method again with a packing \kw{PUP::er} to pack 
+your element into a message.
+\item Call your element's destructor (killing off the old copy).
+\item Send the message (containing your element) across the network.
+\item Call your element's migration constructor on the new processor.
+\item Call your \uw{pup} method on with an unpacking \kw{PUP::er} to unpack 
+the element.
+\item Call your \kw{ckJustMigrated} method
+\end{itemize}
+
+Migration constructors, then, are normally empty-- all the unpacking
+and allocation of the data items is done in the element's \uw{pup} routine.
+Deallocation is done in the element destructor as usual.
+
+
+\subsubsection{Load Balancing Chare Arrays}
+
+see section~\ref{lbFramework}
+
+\subsubsection{Array Section}
+
+\experimental{}
+\label{array section}
+
+\charmpp{} supports array section which is a subset of array 
+elements in a chare array. \charmpp{} also supports array sections
+which are a subset of array elements in multiple chare arrays of the
+same type \ref{cross array section}.
+A special proxy for an array section can be created given a list of array
+indexes of elements.
+Multicast operations are directly supported in array section proxy with
+an unoptimized direct-sending implementation.
+Section reduction is not directly supported by the section proxy. 
+However, an optimized section multicast/reduction 
+library called ''CkMulticast'' is provided as a separate library module,
+which can be plugged in as a delegation of a section proxy for performing
+section-based multicasts and reductions. 
+
+For each chare array "A" declared in a ci file, a section proxy 
+of type "CProxySection\_A" is automatically generated in the decl and def 
+header files. 
+In order to create an array section, a user needs to provide array indexes 
+of all the array section members.
+You can create an array section proxy in your application by 
+invoking ckNew() function of the CProxySection.
+For example, for a 3D array:
+
+\begin{alltt}
+  CkVec<CkArrayIndex3D> elems;    // add array indices
+  for (int i=0; i<10; i++)
+    for (int j=0; j<20; j+=2)
+      for (int k=0; k<30; k+=2)
+         elems.push_back(CkArrayIndex3D(i, j, k));
+  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems.getVec(), elems.size());
+\end{alltt}
+
+Alternatively, one can do the same thing by providing [lbound:ubound:stride] 
+for each dimension:
+
+\begin{alltt}
+  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, 0, 9, 1, 0, 19, 2, 0, 29, 2);
+\end{alltt}
+
+The above codes create a section proxy that contains array elements of 
+[0:9, 0:19:2, 0:29:2].
+
+For user-defined array index other than CkArrayIndex1D to CkArrayIndex6D,
+one needs to use the generic array index type: CkArrayIndex.
+
+\begin{alltt}
+  CkArrayIndex *elems;    // add array indices
+  int numElems;
+  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems, numElems);
+\end{alltt}
+
+Once you have the array section proxy, you can do multicast to all the 
+section members, or send messages to one member using its index that
+is local to the section, like these:
+
+\begin{alltt}
+  CProxySection_Hello proxy;
+  proxy.someEntry(...)          // multicast
+  proxy[0].someEntry(...)       // send to the first element in the section.
+\end{alltt}
+
+You can move the section proxy in a message to another processor, and still 
+safely invoke the entry functions to the section proxy.
+
+In the multicast example above, for a section with k members, total number 
+of k messages will be sent to all the memebers, which is considered 
+inefficient when several members are on a same processor, in which 
+case only one message needs to be sent to that processor and delivered to
+all section members on that processor locally. To support this optimization,
+a separate library called CkMulticast is provided. This library also supports
+section based reduction.
+
+Note: Use of the bulk array constructor (dimensions given in the CkNew
+or CkArrayOptions rather than individual insertion) will allow
+construction to race ahead of several other startup procedures, this
+creates some limitation on the construction delegation and use of
+array section proxies.  For safety, array sections should be
+created in a post constructor entry method.
+
+
+\label {array_section_multicast}
+
+
+To use the library, you need to compile and install CkMulticast library and 
+link your applications against the library using -module:
+
+\begin{alltt}
+  # compile and install the CkMulticast library, do this only once
+  cd charm/net-linux/tmp
+  make multicast
+
+  # link CkMulticast library using -module when compiling application
+  charmc  -o hello hello.o -module CkMulticast -language charm++ 
+\end{alltt}
+
+CkMulticast library is implemented using delegation(Sec. ~\ref{delegation}). 
+A special ''CkMulticastMgr'' Chare Group is created as a 
+deletegation for section multicast/reduction - all the messages sent
+by the section proxy will be passed to the local delegation branch.
+
+To use the CkMulticast delegation, one needs to create the CkMulticastMgr Group 
+first, and then setup the delegation relationship between the section proxy and 
+CkMulticastMgr Group. 
+One only needs to create one CkMulticastMgr Group globally.
+CkMulticastMgr group can serve all multicast/reduction delegations
+for different array sections in an application:
+
+\begin{alltt}
+  CProxySection_Hello sectProxy = CProxySection_Hello::ckNew(...);
+  CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew();
+  CkMulticastMgr *mCastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
+
+  sectProxy.ckSectionDelegate(mCastGrp);  // initialize section proxy
+
+  sectProxy.someEntry(...)           //multicast via delegation library as before
+\end{alltt}
+
+By default, CkMulticastMgr group builds a spanning tree for multicast/reduction
+with a factor of 2 (binary tree).
+One can specify a different factor when creating a CkMulticastMgr group.
+For example,
+
+\begin{alltt}
+  CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew(3);   // factor is 3
+\end{alltt}
+
+Note, to use CkMulticast library, all multicast messages must inherit from 
+CkMcastBaseMsg, as the following.
+Note that CkMcastBaseMsg must come first, this is IMPORTANT for CkMulticast 
+library to retrieve section information out of the message.
+
+
+\begin{alltt}
+class HiMsg : public CkMcastBaseMsg, public CMessage_HiMsg
+\{
+public:
+  int *data;
+\};
+\end{alltt}
+
+Due to this restriction, you need to define message explicitly for multicast 
+entry functions and no parameter marshalling can be used for multicast with 
+CkMulticast library.
+
+\paragraph{Array Section Reduction} 
+
+Since an array element can be members for multiple array sections, 
+there has to be a way for each array element to tell for which array
+section it wants to contribute. For this purpose, a data structure 
+called ''CkSectionInfo'' is created by CkMulticastMgr for each 
+array section that the array element belongs to.
+When doing section reduction, the array element needs to pass the 
+\kw{CkSectionInfo} as a parameter in the \kw{contribute()}. 
+The \kw{CkSectionInfo} can be retrieved
+from a message in a multicast entry function using function call 
+\kw{CkGetSectionInfo}:
+
+\begin{alltt}
+  CkSectionInfo cookie;
+
+  void SayHi(HiMsg *msg)
+  \{
+    CkGetSectionInfo(cookie, msg);     // update section cookie every time
+    int data = thisIndex;
+    mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie);
+  \}
+\end{alltt}
+
+Note that the cookie cannot be used as a one-time local variable in the 
+function, the same cookie is needed for the next contribute. This is 
+because cookie includes some context sensive information for example the 
+reduction counter. Function \kw{CkGetSectionInfo()} only update some part 
+of the data in cookie, not creating a brand new one.
+
+Similar to array reduction, to use section based reduction, a reduction
+client CkCallback object need to be created. You may pass the client callback 
+as an additional parameter to \kw{contribute}. If different contribute calls 
+pass different callbacks, some (unspecified, unreliable) callback will be 
+chosen for use. See the followin example:
+
+\begin{alltt}
+    CkCallback cb(CkIndex_myArrayType::myReductionEntry(NULL),thisProxy); 
+    mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie, cb);
+\end{alltt}
+
+If no member passes a callback to contribute, the reduction will use the 
+default callback. You set the default callback for an array section using the 
+\kw{setReductionClient} call by the section root member. A 
+{\bf CkReductionMsg} message will be passed to this callback, which 
+must delete the message when done.
+
+\begin{alltt}
+  CProxySection_Hello sectProxy;
+  CkMulticastMgr *mcastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
+  mcastGrp->setReductionClient(sectProxy, new CkCallback(...));
+\end{alltt}
+
+Same as in array reduction, users can use built-in reduction 
+types(Section~\ref{builtin_reduction}) or define his/her own reducer functions
+(Section~\ref{new_type_reduction}).
+
+\paragraph{Array section multicast/reduction when migration happens}
+
+Using multicast/reduction, you don't need to worry about array migrations.
+When migration happens, array element in the array section can still use 
+the \kw{CkSectionInfo} it stored previously for doing reduction. 
+Reduction messages will be correctly delivered but may not be as efficient 
+until a new multicast spanning tree is rebuilt internally 
+in \kw{CkMulticastMgr} library. 
+When a new spanning tree is rebuilt, a updated \kw{CkSectionInfo} is 
+passed along with a multicast message, 
+so it is recommended that 
+\kw{CkGetSectionInfo()} function is always called when a multicast 
+message arrives (as shown in the above SayHi example).
+
+In case when a multicast root migrates, one needs to reconstruct the 
+spanning tree to get optimal performance. One will get the following
+warning message if not doing so:
+"Warning: Multicast not optimized after multicast root migrated."
+In current implementation, user needs to initiate the rebuilding process
+like:
+
+\begin{alltt}
+void Foo::pup(PUP::er & p) {
+    // if I am multicast root and it is unpacking
+   if (ismcastroot && p.isUnpacking()) {
+      CProxySection_Foo   fooProxy;    // proxy for the section
+      CkMulticastMgr *mg = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
+      mg->resetSection(fooProxy);
+        // you may want to reset reduction client to root
+      CkCallback *cb = new CkCallback(...);
+      mg->setReductionClient(mcp, cb);
+   }
+}
+\end{alltt}
+
+\paragraph{Cross Array Sections}
+
+
+\experimental{}
+\label{cross array section}
+
+Cross array sections contain elements from multiple arrays.
+Construction and use of cross array sections is similar to normal
+array sections with the following restrictions.  
+
+\begin{itemize}
+
+\item Arrays in a section my all be of the same type.
+
+\item Each array must be enumerated by array ID
+
+\item The elements within each array must be enumerated explicitly
+
+\item No existing modules currently support delegation of cross
+  section proxies.  Therefore reductions are not currently supported.
+
+\end{itemize}
+
+Note: cross section logic also works for groups with analogous characteristics.
+
+Given three arrays declared thusly:
+
+\begin{alltt}
+         CkArrayID *aidArr= new CkArrayID[3];
+         CProxy\_multisectiontest\_array1d *Aproxy= new CProxy\_multisectiontest\_array1d[3];
+         for(int i=0;i<3;i++)
+           \{
+             Aproxy[i]=CProxy\_multisectiontest\_array1d::ckNew(masterproxy.ckGetGroupID(),ArraySize);   
+             aidArr[i]=Aproxy[i].ckGetArrayID();
+           \}
+\end{alltt}
+
+One can make a section including the  lower half elements of all three
+arrays as follows:
+
+\begin{alltt}
+         int aboundary=ArraySize/2;
+         int afloor=aboundary;
+         int aceiling=ArraySize-1;
+         int asectionSize=aceiling-afloor+1;
+         // cross section lower half of each array
+         CkArrayIndex **aelems= new CkArrayIndex*[3];
+         aelems[0]= new CkArrayIndex[asectionSize];
+         aelems[1]= new CkArrayIndex[asectionSize];
+         aelems[2]= new CkArrayIndex[asectionSize];
+         int *naelems=new int[3];
+         for(int k=0;k<3;k++)
+           \{
+             naelems[k]=asectionSize;
+             for(int i=afloor,j=0;i<=aceiling;i++,j++)
+               aelems[k][j]=CkArrayIndex1D(i);
+           \}
+         CProxySection\_multisectiontest\_array1d arrayLowProxy(3,aidArr,aelems,naelems);
+\end{alltt}
+
+
+
+The resulting cross section proxy, as in the example \uw{arrayLowProxy},
+can then be used for multicasts in the same way as a normal array
+section.
+
+Note: For simplicity the example has all arrays and sections of uniform
+size.  The size of each array and the number of elements in each array
+within a section can all be set independently.
+
+
index 52fb60a6b17b850cd85efc330c16a4b46aefcb0d..e063224631feb2c7786d303b92fc1ae662542741 100644 (file)
@@ -3,6 +3,133 @@
 
 \label{advancedlb}
 
+\subsubsection{Load Balancing Simulation}
+
+The simulation feature of load balancing framework allows the users to collect information
+about the compute wall/cpu time and communication of the chares during a particular run of
+the program and use this information to later test different load balancing strategies to
+see which one is suitable for the programs behaviour. Currently, this feature is supported only for
+the centralized load balancing strategies. For this, the load balancing framework
+accepts the following command line options:
+\begin{enumerate}
+\item {\em +LBDump StepStart}\\
+        This will dump the instrument/communication data collected by the load balancing framework
+       starting from the load balancing step {\em StepStart} into a file on the disk. The name of the file
+       is given by the {\em +LBDumpFile} option. The first step in the program is number 0. Negative
+       numbers will be converted to 0.
+\item {\em +LBDumpSteps StepsNo}\\
+        This option specifies the number of steps for which data will be dumped to disk. If omitted, default value is 1.
+       The program will exit after StepsNo files are dumped.
+\item {\em +LBDumpFile FileName}\\
+       This option specifies the base name of the file into which the load balancing data is dumped. If this
+       option is not specified, the framework uses the default file {\tt lbdata.dat}. Since multiple steps are allowed,
+       a number is appended to the filename in the form {\tt Filename.\#}; this applies to both dump and
+       simulation.
+\item {\em +LBSim StepStart}\\
+       This option instructs the framework to do the simulation during the first load balancing step.
+       When this option is specified, the load balancing data from the file specified in the {\em +LBDumpFile}
+       option, with the addition of the step number, will be read and this data
+       will be used for the load balancing. The program will print the results
+       of the balancing for a number of steps given by the {\em +LBSimSteps} option, and then will exit.
+\item {\em +LBSimSteps StepsNo}\\
+        This option has the same meaning of {\em +LBDumpSteps}, except that apply for the simulation mode.
+       Default value is 1.
+\item {\em +LBSimProcs}\\
+        This option may change the number of processors target of the load balancer strategy. It may be used to test
+       the load balancer in conditions where some processor crashes or someone becomes available. If this number is not
+       changed since the original run, starting from the second step file the program will print other additional
+       information about how the simulated load differs from the real load during the run (considering all
+       strategies that were applied while running). This may be used to test the validity of a load balancer
+       prediction over the reality. If the strategies used during run and simulation differ, the additional data
+       printed may not be useful.
+\end{enumerate}
+As an example, we can collect the data for a 1000 processor run of a program using:
+\begin{alltt}
+./charmrun pgm +p 1000 +balancer RandCentLB +LBDump 2 +LBDumpSteps 4 +LBDumpFile dump.dat
+\end{alltt}
+This will collect data on files data.dat.{2,3,4,5}. Then, we can use this data to observe various centralized strategies using:
+\begin{alltt}
+./charmrun pgm +balancer <Strategy to test> +LBSim 2 +LBSimSteps 4 +LBDumpFile dump.dat [+LBSimProcs 900]
+\end{alltt}
+
+\subsubsection{Future load predictor}
+
+When objects do not follow the assumption that the future workload will be the
+same as the past, the load balancer might not have the correct information to do
+a correct rebalancing job. To prevent this the user can provide a transition
+function to the load balancer to predict what will be the future workload, given
+the past, instrumented one. As said, the user might provide a specific class
+which inherits from {\tt LBPredictorFunction} and implement the appropriate functions. 
+Here is the abstract class:
+\begin{alltt}
+class LBPredictorFunction {
+public:
+  int num_params;
+  virtual void initialize_params(double *x);
+
+  virtual double predict(double x, double *params) =0;
+  virtual void print(double *params) {PredictorPrintf("LB: unknown model");};
+  virtual void function(double x, double *param, double &y, double *dyda) =0;
+};
+\end{alltt}
+\begin{itemize}
+\item {\tt initialize\_params} by default initializes the parameters randomly. If the user
+knows how they should be, this function can be reimplemented.
+\item {\tt predict} is the function the model implements. For example, if the function is
+$y=ax+b$, the method in the implemented class should be like:
+\begin{verbatim}
+double predict(double x, double *param) {return (param[0]*x + param[1]);}
+\end{verbatim}
+\item {\tt print} is a debugging function and it can be reimplemented to have a meaningful
+print of the learnt model
+\item {\tt function} is a function internally needed to learn the parameters, {\tt x} and
+{\tt param} are input, {\tt y} and {\tt dyda} are output (the computed function and
+all its derivatives with respect to the parameters, respectively).
+For the function in the example should look like:
+\begin{verbatim}
+void function(double x, double *param, double &y, double *dyda) {
+  y = predict(x, param);
+  dyda[0] = x;
+  dyda[1] = 1;
+}
+\end{verbatim}
+\end{itemize}
+Other than these function, the user should provide a constructor which must initialize
+{\tt num\_params} to the number of parameters the model has to learn. This number is
+the dimension of {\tt param} and {\tt dyda} in the previous functions. For the given
+example, the constructor is {\tt \{num\_params = 2;\}}.
+
+If the model behind the computation is not known, the user can leave the system to
+use a predefined default function.
+
+As seen, the function can have several parameters which will be learned during
+the execution of the program. For this, two parameters can be setup at command
+line to specify the learning behaviour:
+\begin{enumerate}
+\item {\em +LBPredictorWindow size}\\
+This parameter will specify how many statistics the load balancer will keep. 
+The greater this number is, the better the
+approximation of the workload will be, but more memory is required to store
+the intermediate information. The default is 20.
+\item {\em +LBPredictorDelay steps}\\
+This will tell how many load balancer steps to wait before considering the
+function parameters learnt and start using the mode. The load balancer will
+collect statistics for a {\em +LBPredictorWindow} steps, but it will start using
+the model as soon as {\em +LBPredictorDelay} information are collected. The
+default is 10.
+\end{enumerate}
+Moreover another flag can be set to enable the predictor from command line: {\em
++LBPredictor}.\\
+Other than the command line options, there are some methods
+callable from user program to modify the predictor. These methods are:
+\begin{itemize}
+\item {\tt void PredictorOn(LBPredictorFunction *model);}
+\item {\tt void PredictorOn(LBPredictorFunction *model,int wind);}
+\item {\tt void PredictorOff();}
+\item {\tt void ChangePredictor(LBPredictorFunction *model);}
+\end{itemize}
+
 \subsubsection{Control CPU Load Statistics}
 
 Charm++ programmers can control CPU load data in the load balancing database
diff --git a/doc/charm++/advancedpup.tex b/doc/charm++/advancedpup.tex
new file mode 100644 (file)
index 0000000..81106f7
--- /dev/null
@@ -0,0 +1,525 @@
+\subsection{Advanced PUP}
+
+\subsubsection{Dynamic Allocation}
+
+\label{sec:pupdynalloc}
+
+If your class has fields that are dynamically allocated, when unpacking
+these need to be allocated (in the usual way) before you pup them.
+Deallocation should be left to the class destructor as usual.
+
+\paragraph{No allocation}
+
+The simplest case is when there is no dynamic allocation.
+\begin{alltt}
+class keepsFoo : public mySuperclass \{
+private:
+    foo f; /* simple foo object*/
+public:
+    keepsFoo(void) \{ \}
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      p|f; // pup f's fields (calls f.pup(p);) 
+    \}
+    ~keepsFoo() \{ \}
+\};
+\end{alltt}
+
+\paragraph{Allocation outside pup}
+
+The next simplest case is when we contain a class 
+that is always allocated during our constructor,
+and deallocated during our destructor.  Then no allocation
+is needed within the pup routine.
+\begin{alltt}
+class keepsHeapFoo : public mySuperclass \{
+private:
+    foo *f; /*Heap-allocated foo object*/
+public:
+    keepsHeapFoo(void) \{
+      f=new foo;
+    \}
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      p|*f; // pup f's fields (calls f->pup(p))
+    \}
+    ~keepsHeapFoo() \{delete f;\}
+\};
+\end{alltt}
+
+\paragraph{Allocation during pup}
+
+If we need values obtained during the pup routine
+before we can allocate the class, we must 
+allocate the class inside the pup routine.
+Be sure to protect the allocation with ``if (p.isUnpacking())''.
+\begin{alltt}
+class keepsOneFoo : public mySuperclass \{
+private:
+    foo *f; /*Heap-allocated foo object*/
+public:
+    keepsOneFoo(...) \{f=new foo(...);\}
+    keepsOneFoo() \{f=NULL;\} /* pup constructor */
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      ...
+      if (p.isUnpacking()) /* must allocate foo now */
+         f=new foo(...);
+      p|*f;//pup f's fields
+    \}
+    ~keepsOneFoo() \{delete f;\}
+\};
+\end{alltt}
+
+\paragraph{Allocatable array}
+
+For example, if we keep an array of doubles,
+we need to know how many doubles there are 
+before we can allocate the array.  Hence we must
+first pup the array length, do our allocation,
+and then pup the array data.  We could allocate memory using 
+malloc/free or other allocators in exactly the same way.
+\begin{alltt}
+class keepsDoubles : public mySuperclass \{
+private:
+    int n;
+    double *arr;/*new'd array of n doubles*/
+public:
+    keepsDoubles(int n_) \{
+      n=n_;
+      arr=new double[n];
+    \}
+    keepsDoubles() \{ \} 
+    
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      p|n;//pup the array length n
+      if (p.isUnpacking())  arr=new double[n];
+      PUParray(p,arr,n); //pup data in the array
+    \}
+    
+    ~keepsDoubles() \{delete[] arr;\}
+\};
+\end{alltt}
+
+\paragraph{NULL object pointer}
+
+If our allocated object may be NULL, our allocation
+becomes much more complicated.  We must first check
+and pup a flag to indicate whether the object exists, 
+then depending on the flag, pup the object.
+\begin{alltt}
+class keepsNullFoo : public mySuperclass \{
+private:
+    foo *f; /*Heap-allocated foo object, or NULL*/
+public:
+    keepsNullFoo(...) \{ if (...) f=new foo(...);\}
+    keepsNullFoo() \{f=NULL;\}
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      int has_f=(f!=NULL);
+      p|has_f;
+      if (has_f) {
+        if (p.isUnpacking()) f=new foo;
+        p|*f;
+      } else {
+        f=NULL;
+      }
+    \}
+    ~keepsNullFoo() \{delete f;\}
+\};
+\end{alltt}
+
+This sort of code is normally much longer and more
+error-prone if split into the various packing/unpacking cases.
+
+\paragraph{Array of classes}
+
+An array of actual classes can be treated exactly the same way
+as an array of basic types.  PUParray will pup each 
+element of the array properly, calling the appropriate \verb.operator|..
+\begin{alltt}
+class keepsFoos : public mySuperclass \{
+private:
+    int n;
+    foo *arr;/*new'd array of n foos*/
+public:
+    keepsFoos(int n_) \{
+      n=n_;
+      arr=new foo[n];
+    \}
+    keepsFoos() \{ arr=NULL; \} 
+    
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      p|n;//pup the array length n
+      if (p.isUnpacking())  arr=new foo[n];
+      PUParray(p,arr,n); //pup each foo in the array
+    \}
+    
+    ~keepsFoos() \{delete[] arr;\}
+\};
+\end{alltt}
+
+
+\paragraph{Array of pointers to classes}
+
+An array of pointers to classes must handle each element
+separately, since the PUParray routine does not work with 
+pointers.  An ``allocate'' routine to set up the array
+could simplify this code.  More ambitious is to construct
+a ``smart pointer'' class that includes a pup routine.
+\begin{alltt}
+class keepsFooPtrs : public mySuperclass \{
+private:
+    int n;
+    foo **arr;/*new'd array of n pointer-to-foos*/
+public:
+    keepsFooPtrs(int n_) \{
+      n=n_;
+      arr=new foo*[n]; // allocate array
+      for (int i=0;i<n;i++) arr[i]=new foo(...); // allocate i'th foo
+    \}
+    keepsFooPtrs() \{ arr=NULL; \} 
+    
+    void pup(PUP::er &p) \{
+      mySuperclass::pup(p);
+      p|n;//pup the array length n
+      if (p.isUnpacking()) arr=new foo*[n]; // allocate array
+      for (int i=0;i<n;i++) \{
+        if (p.isUnpacking()) arr[i]=new foo(...); // allocate i'th foo
+        p|*arr[i];  //pup the i'th foo
+      \}
+    \}
+    
+    ~keepsFooPtrs() \{
+       for (int i=0;i<n;i++) delete arr[i];
+       delete[] arr;
+     \}
+\};
+\end{alltt}
+
+Note that this will not properly handle the case where
+some elements of the array are actually subclasses of foo,
+with virtual methods.  The PUP::able framework described
+in the next section can be helpful in this case.
+
+
+\subsubsection{Subclass allocation via PUP::able}
+
+\label{sec:pup::able}
+If the class \uw{foo} above might have been a subclass, instead of
+simply using \uw{new foo} above we would have had to allocate 
+an object of the appropriate subclass.  Since determining the
+proper subclass and calling the appropriate constructor yourself can be 
+difficult, the PUP framework provides a scheme for automatically
+determining and dynamically allocating subobjects of the appropriate type.
+
+Your superclass must inherit from \kw{PUP::able}, which provides 
+the basic machinery used to move the class.  
+A concrete superclass and all its concrete subclasses require these
+four features:
+
+\begin{itemize}
+\item A line declaring \kw{PUPable \uw{className};} in the .ci file.
+This registers the class's constructor.
+
+\item A call to the macro \kw{PUPable\_decl(\uw{className})} in the
+class's declaration, in the header file.  This adds a virtual 
+method to your class to allow \kw{PUP::able} to determine your class's type.
+
+\item A migration constructor---a constructor that takes \kw{CkMigrateMessage *}.
+This is used to create the new object on the receive side, immediately
+before calling the new object's \kw{pup} routine.
+
+\item A working, virtual \kw{pup} method.  You can omit this if your
+class has no data that needs to be packed.
+\end{itemize}
+
+An abstract superclass---a superclass that will never actually be 
+packed---only needs to inherit from \kw{PUP::able} and include a 
+\kw{PUPable\_abstract(\uw{className})} macro in their body.  For
+these abstract classes, the 
+.ci file, \kw{PUPable\_decl} macro, and constructor are not needed.
+
+For example, if \uw{parent} is a concrete superclass and \uw{child} its
+subclass,
+
+\begin{alltt}
+//In the .ci file:
+   PUPable parent;
+   PUPable child; //Could also have said ``PUPable parent, child;''
+
+//In the .h file:
+class parent : public PUP::able \{
+    ... data members ...
+public:
+    ... other methods ...
+    parent() \{...\}
+    
+    //PUP::able support: decl, migration constructor, and pup
+    PUPable\_decl(parent);  
+    parent(CkMigrateMessage *m) : PUP::able(m) \{\}
+    virtual void pup(PUP::er &p) \{
+        PUP::able::pup(p);//Call base class
+        ... pup data members as usual ...
+    \}  
+\};
+class child : public parent \{
+    ... more data members ...
+public:    ... more methods, possibly virtual ...
+    child() \{...\}
+    
+    //PUP::able support: decl, migration constructor, and pup
+    PUPable\_decl(child);  
+    child(CkMigrateMessage *m) : parent(m) \{\}
+    virtual void pup(PUP::er &p) \{
+        parent::pup(p);//Call base class
+        ... pup child's data members as usual ...
+    \}  
+\};
+
+\end{alltt}
+
+With these declarations, then, we can automatically 
+allocate and pup a pointer to a parent or child
+using the vertical bar \kw{PUP::er} syntax, which on the receive
+side will create a new object of the appropriate type:
+
+\begin{alltt}
+class keepsParent \{
+    parent *obj; //May actually point to a child class (or be NULL)
+public:
+    ...
+    ~keepsParent() \{
+        delete obj;
+    \}
+    void pup(PUP::er &p) 
+    \{
+        p|obj;
+    \}
+\};
+PUPmarshall(keepsParent);
+\end{alltt}
+
+This will properly pack, allocate, and unpack obj whether
+it is actually a parent or child object.  The child class 
+can use all the usual \CC\ features, such as virtual functions
+and extra private data.
+
+If obj is NULL when packed, it will be restored to NULL when unpacked.
+For example, if the nodes of a binary tree are \kw{PUP::able},
+one may write a recursive pup routine for the tree quite easily:
+
+\begin{alltt}
+// In the .ci file:
+    PUPable treeNode;
+
+// In the .h file
+class treeNode : public PUP::able \{
+    treeNode *left;//Left subtree
+    treeNode *right;//Right subtree
+    ... other fields ...
+public:
+    treeNode(treeNode *l=NULL, treeNode *r=NULL);
+    ~treeNode() \{delete left; delete right;\}
+    
+    // The usual PUP::able support:
+    PUPable\_decl(treeNode);
+    treeNode(CkMigrateMessage *m) : PUP::able(m) \{ left=right=NULL; \}
+    void pup(PUP::er &p) \{
+        PUP::able::pup(p);//Call base class
+        p|left;
+        p|right;
+        ... pup other fields as usual ...
+    \}
+\};
+\end{alltt}
+
+This same implementation will also work properly even if the tree's
+internal nodes are actually subclasses of treeNode.
+
+You may prefer to use the macros \kw{PUPable\_def(\uw{className})}
+and \kw{PUPable\_reg(\uw{className})} rather than using \kw{PUPable}
+in the .ci file.  \kw{PUPable\_def} provides routine definitions used
+by the \kw{PUP::able} machinery, and should be included in exactly one
+source file at file scope.  \kw{PUPable\_reg} registers this class
+with the runtime system, and should be executed exactly once per node 
+during program startup.
+
+Finally, a \kw{PUP::able} superclass like \uw{parent} above 
+must normally be passed around via a pointer or reference, because the object
+might actually be some subclass like \uw{child}.  Because
+pointers and references cannot be passed across processors,
+for parameter marshalling you must use the special templated 
+smart pointer classes \kw{CkPointer} and \kw{CkReference},
+which only need to be listed in the .ci file.
+
+A \kw{CkReference} is a read-only reference to a \kw{PUP::able} object---it
+is only valid for the duration of the method call.  A \kw{CkPointer}
+transfers ownership of the unmarshalled \kw{PUP::able} to the method, so the 
+pointer can be kept and the object used indefinitely.  
+
+For example, if the entry method \uw{bar} needs a \kw{PUP::able} \uw{parent}
+object for in-call processing, you would use a \kw{CkReference} like this:
+
+\begin{alltt}
+// In the .ci file:
+    entry void barRef(int x,CkReference<parent> p);
+
+// In the .h file:
+    void barRef(int x,parent &p) \{
+      // can use p here, but only during this method invocation
+    \}
+\end{alltt}
+
+If the entry method needs to keep its parameter, use a \kw{CkPointer} like this:
+\begin{alltt}
+// In the .ci file:
+    entry void barPtr(int x,CkPointer<parent> p);
+
+// In the .h file:
+    void barPtr(int x,parent *p) \{
+      // can keep this pointer indefinitely, but must eventually delete it
+    \}
+\end{alltt}
+
+Both \kw{CkReference} and \kw{CkPointer} are read-only from the send 
+side---unlike messages, which are consumed when sent, the same object 
+can be passed to several parameter marshalled entry methods.
+In the example above, we could do:
+
+\begin{alltt}
+   parent *p=new child;
+   someProxy.barRef(x,*p);
+   someProxy.barPtr(x,p); // Makes a copy of p
+   delete p; // We allocated p, so we destroy it.
+\end{alltt}
+
+
+\subsubsection{C and Fortran bindings}
+
+C and Fortran programmers can use a limited subset of the
+\kw{PUP::er} capability.  The routines all take a 
+handle named \kw{pup\_er}.  The routines 
+have the prototype:
+\begin{alltt}
+void pup\_\kw{type}(pup\_er p,\kw{type} *val);
+void pup\_\kw{type}s(pup\_er p,\kw{type} *vals,int nVals);
+\end{alltt}
+The first call is for use with a single element;
+the second call is for use with an array.
+The supported types are char, short, int, long,
+uchar, ushort, uint, ulong, float, and double,
+which all have the usual C meanings.
+
+A byte-packing routine
+\begin{alltt}
+void pup\_bytes(pup\_er p,void *data,int nBytes);
+\end{alltt}
+is also provided, but its use is discouraged
+for cross-platform puping.
+
+\kw{pup\_isSizing}, \kw{pup\_isPacking}, \kw{pup\_isUnpacking},
+and \kw{pup\_isDeleting} calls are also available.
+Since C and Fortran have no destructors, you should 
+actually deallocate all data when passed a deleting \kw{pup\_er}.
+
+C and Fortran users cannot use \kw{PUP::able} objects, 
+seeking, or write custom \kw{PUP::er}s. Using the \CC\
+interface is recommended.
+
+
+
+\subsubsection{Common PUP::ers}
+
+The most common \kw{PUP::er}s used are \kw{PUP::sizer},
+\kw{PUP::toMem}, and \kw{PUP::fromMem}.  These are sizing,
+packing, and unpacking \kw{PUP::er}s, respectively.
+
+\kw{PUP::sizer} simply sums up the sizes of the native
+binary representation of the objects it is passed.
+\kw{PUP::toMem} copies the binary representation of the
+objects passed into a preallocated contiguous memory buffer.
+\kw{PUP::fromMem} copies binary data from a contiguous memory
+buffer into the objects passed.  All three support the
+\kw{size} method, which returns the number of bytes used
+by the objects seen so far.
+
+Other common \kw{PUP::er}s are \kw{PUP::toDisk}, 
+\kw{PUP::fromDisk}, and \kw{PUP::xlater}.  The first
+two are simple filesystem variants of the \kw{PUP::toMem} 
+and \kw{PUP::fromMem} classes; \kw{PUP::xlater} translates
+binary data from an unpacking PUP::er into the machine's
+native binary format, based on a \kw{machineInfo} structure
+that describes the format used by the source machine.
+
+
+\subsubsection{PUP::seekBlock}
+
+It may rarely occur that you require items to be unpacked
+in a different order than they are packed.  That is, you
+want a seek capability.  \kw{PUP::er}s support a limited 
+form of seeking.
+
+To begin a seek block, create a \kw{PUP::seekBlock} object
+with your current PUP::er and the number of ``sections'' to 
+create.  Seek to a (0-based) section number
+with the seek method, and end the seeking with the endBlock method.
+For example, if we have two objects A and B, where A's pup
+depends on and affects some object B, we can pup the two with:
+
+\begin{alltt}
+void pupAB(PUP::er &p)
+\{
+  ... other fields ...
+  PUP::seekBlock s(p,2); //2 seek sections
+  if (p.isUnpacking()) 
+  \{//In this case, pup B first
+    s.seek(1);
+    B.pup(p);
+  \}
+  s.seek(0);
+  A.pup(p,B);
+  
+  if (!p.isUnpacking()) 
+  \{//In this case, pup B last
+    s.seek(1);
+    B.pup(p);
+  \}
+  s.endBlock(); //End of seeking block
+  ... other fields ...
+\};
+\end{alltt}
+
+Note that without the seek block, A's fields would be unpacked
+over B's memory, with disasterous consequences.
+The packing or sizing path must traverse the seek sections
+in numerical order; the unpack path may traverse them in any
+order.  There is currently a small fixed limit of 3 on the 
+maximum number of seek sections.
+
+
+\subsubsection{Writing a PUP::er}
+
+System-level programmers may occasionally find it useful to define
+their own \kw{PUP::er} objects.  The system \kw{PUP::er} class is 
+an abstract base class that funnels all incoming pup requests
+to a single subroutine:
+
+\begin{alltt}
+    virtual void bytes(void *p,int n,size\_t itemSize,dataType t);
+\end{alltt}
+
+The parameters are, in order, the field address, the number of items,
+the size of each item, and the type of the items. The \kw{PUP::er}
+is allowed to use these fields in any way.  However, an isSizing
+or isPacking PUP::er may not modify the referenced user data; 
+while an isUnpacking PUP::er may not read the original values of 
+the user data.  If your PUP::er is not clearly packing (saving values
+to some format) or unpacking (restoring values), declare it as 
+sizing \kw{PUP::er}.
+
+
+
+
index e57fe181988e09fc33ff23e7287f1c1adf6a000c..21aa056cfb5f1119a5bf3c935a6a10fe7d958cee 100644 (file)
@@ -61,6 +61,58 @@ A::A(CkMigrateMessage *m) \{ \}
 Read the section ``Migratable Array Elements'' for more
 information on the \kw{CkMigrateMessage} constructor. 
 
+\subsubsection{Declaring Multidimensional Arrays}
+
+\charmpp{} contains direct support for multidimensional and
+even user-defined index arrays.  These arrays can be declared as:
+
+\begin{alltt}
+//In the .ci file:
+message MyMsg;
+array [1D] A1 \{ entry A1(); entry void e(\uw{parameters});\}
+array [2D] A2 \{ entry A2(); entry void e(\uw{parameters});\}
+array [3D] A3 \{ entry A3(); entry void e(\uw{parameters});\}
+array [4D] A4 \{ entry A4(); entry void e(\uw{parameters});\}
+array [5D] A5 \{ entry A5(); entry void e(\uw{parameters});\}
+array [6D] A6 \{ entry A6(); entry void e(\uw{parameters});\}
+array [Foo] AF \{ entry AF(); entry void e(\uw{parameters});\}
+\end{alltt}
+
+The last declaration expects an array index of type \kw{CkArrayIndex}\uw{Foo},
+which must be defined before including the \texttt{.decl.h} file 
+(see ``User-defined array index type'' below).  
+
+\begin{alltt}
+//In the .h file:
+class A1 : public CBase\_A1 \{ public: A1()\{\} ...\};
+class A2 : public CBase\_A2 \{ public: A2()\{\} ...\};
+class A3 : public CBase\_A3 \{ public: A3()\{\} ...\};
+class A4 : public CBase\_A4 \{ public: A4()\{\} ...\};
+class A5 : public CBase\_A5 \{ public: A5()\{\} ...\};
+class A6 : public CBase\_A6 \{ public: A6()\{\} ...\};
+class AF : public CBase\_AF \{ public: AF()\{\} ...\};
+\end{alltt}
+
+A 1D array element can access its index via its inherited ``thisIndex''
+field; a 2D via ``thisIndex.x'' and ``thisIndex.y'', and a 3D via
+``thisIndex.x'', ``thisIndex.y'', and ``thisIndex.z''. The subfields
+of 4D, 5D, and 6D are respectively \{w,x,y,z\}, \{v,w,x,y,z\}, and 
+\{x1,y1,z1,x2,y2,z2\}.
+A user-defined index array can access its index as ``thisIndex''.
+
+
+Likewise, you can create a dense multidimensional array by passing the 
+extents at creation time to \kw{ckNew}.
+
+\begin{alltt}
+CProxy_A1 a1 = CProxy_A1::ckNew(parameters, num_elements);
+CProxy_A2 a2 = CProxy_A2::ckNew(parameters, num_rows, num_colums);
+CProxy_A3 a3 = CProxy_A3::ckNew(parameters, num_rows, num_columns, num_depth);
+\end{alltt}
+
+For 4D, 5D, 6D and user-defined arrays, this functionality cannot be used. 
+You need to insert the array elements individually (Section~\ref{dynamic_insertion}).
+
 
 \subsubsection{Creating a Simple Array}
 
@@ -81,7 +133,7 @@ For creating higher-dimensional arrays, or for more options
 when creating the array, see section~\ref{advanced array create}.
 
 
-\subsubsection{Messages}
+\subsubsection{Entry Method Invocation}
 
 An array proxy responds to the appropriate index call--
 for 1D arrays, use [i] or (i); for 2D use (x,y); for 3D
@@ -160,928 +212,111 @@ You must ensure that no messages are sent to a deleted element.
 After destroying an element, you may insert a new element at
 its index.
 
+\subsubsection{Array Reductions}
 
+\label{reductions}
 
+A \index{array 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
+over the members of an array or group.
 
-\subsection{Advanced Arrays}
-
-\label{advanced arrays}
-
-The basic array features described above (creation, messaging,
-broadcasts, and reductions) are needed in almost every
-\charmpp{} program.  The more advanced techniques that follow
-are not universally needed; but are still often useful.
-
-
-\subsubsection{Declaring Multidimensional, or User-defined Index Arrays}
-
-\charmpp{} contains direct support for multidimensional and
-even user-defined index arrays.  These arrays can be declared as:
-
-\begin{alltt}
-//In the .ci file:
-message MyMsg;
-array [1D] A1 \{ entry A1(); entry void e(\uw{parameters});\}
-array [2D] A2 \{ entry A2(); entry void e(\uw{parameters});\}
-array [3D] A3 \{ entry A3(); entry void e(\uw{parameters});\}
-array [4D] A4 \{ entry A4(); entry void e(\uw{parameters});\}
-array [5D] A5 \{ entry A5(); entry void e(\uw{parameters});\}
-array [6D] A6 \{ entry A6(); entry void e(\uw{parameters});\}
-array [Foo] AF \{ entry AF(); entry void e(\uw{parameters});\}
-\end{alltt}
-
-The last declaration expects an array index of type \kw{CkArrayIndex}\uw{Foo},
-which must be defined before including the \texttt{.decl.h} file 
-(see ``User-defined array index type'' below).  
-
-\begin{alltt}
-//In the .h file:
-class A1 : public CBase\_A1 \{ public: A1()\{\} ...\};
-class A2 : public CBase\_A2 \{ public: A2()\{\} ...\};
-class A3 : public CBase\_A3 \{ public: A3()\{\} ...\};
-class A4 : public CBase\_A4 \{ public: A4()\{\} ...\};
-class A5 : public CBase\_A5 \{ public: A5()\{\} ...\};
-class A6 : public CBase\_A6 \{ public: A6()\{\} ...\};
-class AF : public CBase\_AF \{ public: AF()\{\} ...\};
-\end{alltt}
-
-A 1D array element can access its index via its inherited ``thisIndex''
-field; a 2D via ``thisIndex.x'' and ``thisIndex.y'', and a 3D via
-``thisIndex.x'', ``thisIndex.y'', and ``thisIndex.z''. The subfields
-of 4D, 5D, and 6D are respectively \{w,x,y,z\}, \{v,w,x,y,z\}, and 
-\{x1,y1,z1,x2,y2,z2\}.
-A user-defined index array can access its index as ``thisIndex''.
-
-
-Likewise, you can create a dense multidimensional array by passing the 
-extents at creation time to \kw{ckNew}.
-
-\begin{alltt}
-CProxy_A1 a1 = CProxy_A1::ckNew(parameters, num_elements);
-CProxy_A2 a2 = CProxy_A2::ckNew(parameters, num_rows, num_colums);
-CProxy_A3 a3 = CProxy_A3::ckNew(parameters, num_rows, num_columns, num_depth);
-\end{alltt}
-
-For 4D, 5D, 6D and user-defined arrays, this functionality cannot be used. 
-You need to insert the array elements individually (Section~\ref{dynamic_insertion}).
-
-\subsubsection{Advanced Array Creation}
-
-\label{advanced array create}
-There are several ways to control the array creation process.
-You can adjust the map and bindings before creation, change
-the way the initial array elements are created, create elements
-explicitly during the computation, and create elements implicitly,
-``on demand''.  
-
-You can create all your elements using any one of these methods,
-or create different elements using different methods.  
-An array element has the same syntax and semantics no matter
-how it was created.
-
-
-\subsubsection{Advanced Array Creation: CkArrayOptions}
-
-\index{CkArrayOptions}
-\label{CkArrayOptions}
-
-The array creation method \kw{ckNew} actually takes a parameter
-of type \kw{CkArrayOptions}.  This object describes several
-optional attributes of the new array.
-
-The most common form of \kw{CkArrayOptions} is to set the number
-of initial array elements.  A \kw{CkArrayOptions} object will be 
-constructed automatically in this special common case.  Thus
-the following code segments all do exactly the same thing:
-
-\begin{alltt}
-//Implicit CkArrayOptions
-  a1=CProxy_A1::ckNew(\uw{parameters},nElements);
-
-//Explicit CkArrayOptions
-  a1=CProxy_A1::ckNew(\uw{parameters},CkArrayOptions(nElements));
-
-//Separate CkArrayOptions
-  CkArrayOptions opts(nElements);
-  a1=CProxy_A1::ckNew(\uw{parameters},opts);
-\end{alltt}
-
-Note that the ``numElements'' in an array element is simply the
-numElements passed in when the array was created.  The true number of
-array elements may grow or shrink during the course of the
-computation, so numElements can become out of date.  This ``bulk''
-constructor approach should be preferred where possible, especially
-for large arrays.  Bulk construction is handled via a broadcast which
-will be significantly more efficient in the number of messages
-required than inserting each element individually which will require
-one message send per element.
-
-\kw{CkArrayOptions} contains a few flags that the runtime can use to
-optimize handling of a given array. If the array elements will only
-migrate at controlled points (such as periodic load balancing with
-{\tt AtASync()}), this is signalled to the runtime by calling {\tt
-  opts.setAnytimeMigration(false)}\footnote{At present, this optimizes
-broadcasts to not save old messages for immigrating chares.}. If all
-array elements will be inserted by bulk creation or by {\tt
-  fooArray[x].insert()} calls, signal this by calling {\tt
-  opts.setStaticInsertion(true)} \footnote{This can enable a slightly
-  faster default mapping scheme.}.
-
-\subsubsection{Advanced Array Creation: Map Object}
-
-\index{array map}
-\label{array map}
-
-You can use \kw{CkArrayOptions} to specify a ``map object''
-for an array.  The map object is used by the array manager
-to determine the ``home'' processor of each element.  The
-home processor is the processor responsible for maintaining
-the location of the element.
-
-There is a default map object, which maps 1D array indices
-in a block fashion to processors, and maps other array
-indices based on a hash function. Some other mappings such as round-robin
-(\kw{RRMap}) also exist, which can be used
-similar to custom ones described below.
-
-A custom map object is implemented as a group which inherits from
-\kw{CkArrayMap} and defines these virtual methods:
-
-\begin{alltt}
-class CkArrayMap : public Group
-\{
-public:
-  //...
-  
-  //Return an ``arrayHdl'', given some information about the array
-  virtual int registerArray(CkArrayIndex& numElements,CkArrayID aid);
-  //Return the home processor number for this element of this array
-  virtual int procNum(int arrayHdl,const CkArrayIndex &element);
-\}
-\end{alltt}
-
-For example, a simple 1D blockmapping scheme.  Actual mapping is
-handled in the procNum function.
-
-\begin{alltt}
-class BlockMap : public CkArrayMap 
-\{
- public:
-  BlockMap(void) \{\}
-  BlockMap(CkMigrateMessage *m)\{\}
-  int registerArray(CkArrayIndex& numElements,CkArrayID aid) \{
-    return 0;
-  \}
-  int procNum(int /*arrayHdl*/,const CkArrayIndex &idx) \{
-    int elem=*(int *)idx.data();
-    int penum =  (elem/(32/CkNumPes()));
-    return penum;
-  \}
-\};
-
-\end{alltt}
-Once you've instantiated a custom map object, you can use it to
-control the location of a new array's elements using the
-\kw{setMap} method of the \kw{CkArrayOptions} object described above.
-For example, if you've declared a map object named ``BlockMap'':
-
-\begin{alltt}
-//Create the map group
-  CProxy_BlockMap myMap=CProxy_BlockMap::ckNew();
-//Make a new array using that map
-  CkArrayOptions opts(nElements);
-  opts.setMap(myMap);
-  a1=CProxy_A1::ckNew(\uw{parameters},opts);
-\end{alltt}
-
-
-
-\subsubsection{Advanced Array Creation: Initial Elements}
-
-\index{array initial}
-\label{array initial}
-
-The map object described above can also be used to create
-the initial set of array elements in a distributed fashion.
-An array's initial elements are created by its map object,
-by making a call to \kw{populateInitial} on each processor.
-
-You can create your own set of elements by creating your
-own map object and overriding this virtual function of \kw{CkArrayMap}:
-
-\begin{alltt}
-  virtual void populateInitial(int arrayHdl,int numInitial,
-       void *msg,CkArrMgr *mgr)
-\end{alltt}
-
-In this call, \kw{arrayHdl} is the value returned by \kw{registerArray},
-\kw{numInitial} is the number of elements passed to \kw{CkArrayOptions},
-\kw{msg} is the constructor message to pass, and \kw{mgr} is the
-array to create.
-
-\kw{populateInitial} creates new array elements using the method
-\kw{void CkArrMgr::insertInitial(CkArrayIndex idx,void *ctorMsg)}.
-For example, to create one row of 2D array elements on each processor,
-you would write:
-
-\begin{alltt}
-void xyElementMap::populateInitial(int arrayHdl,int numInitial,
-       void *msg,CkArrMgr *mgr)
-\{
-  if (numInitial==0) return; //No initial elements requested
-       
-  //Create each local element
-  int y=CkMyPe();
-  for (int x=0;x<numInitial;x++) \{
-    mgr->insertInitial(CkArrayIndex2D(x,y),CkCopyMsg(&msg));
-  \}
-  mgr->doneInserting();
-  CkFreeMsg(msg);
-\}
-\end{alltt}
-
-Thus calling \kw{ckNew(10)} on a 3-processor machine would result in
-30 elements being created.
-
-
-\subsubsection{Advanced Array Creation: Bound Arrays}
-
-\experimental{}
-\index{bound arrays} \index{bindTo}
-\label{bound arrays}
-You can ``bind'' a new array to an existing array
-using the \kw{bindTo} method of \kw{CkArrayOptions}.  Bound arrays
-act like separate arrays in all ways except for migration--
-corresponding elements of bound arrays always migrate together.
-For example, this code creates two arrays A and B which are
-bound together-- A[i] and B[i] will always be on the same processor.
-
-\begin{alltt}
-//Create the first array normally
-  aProxy=CProxy_A::ckNew(\uw{parameters},nElements);
-//Create the second array bound to the first
-  CkArrayOptions opts(nElements);
-  opts.bindTo(aProxy);
-  bProxy=CProxy_B::ckNew(\uw{parameters},opts);
-\end{alltt}
-
-An arbitrary number of arrays can be bound together--
-in the example above, we could create yet another array
-C and bind it to A or B.  The result would be the same
-in either case-- A[i], B[i], and C[i] will always be
-on the same processor.
-
-There is no relationship between the types of bound arrays--
-it is permissible to bind arrays of different types or of the
-same type.  It is also permissible to have different numbers
-of elements in the arrays, although elements of A which have
-no corresponding element in B obey no special semantics.
-Any method may be used to create the elements of any bound
-array.
-
-Bound arrays are often useful if A[i] and B[i] perform different 
-aspects of the same computation, and thus will run most efficiently 
-if they lie on the same processor.  Bound array elements are guaranteed
-to always be able to interact using \kw{ckLocal} (see 
-section~\ref{ckLocal for arrays}), although the local pointer must
-be refreshed after any migration. This should be done during the \kw{pup}
-routine. When migrated, all elements that are bound together will be created
-at the new processor before \kw{pup} is called on any of them, ensuring that
-a valid local pointer to any of the bound objects can be obtained during the
-\kw{pup} routine of any of the others.
-
-For example, an array {\it Alibrary} is implemented as a library module.
-It implements a certain functionality by operating on a data array {\it dest}
-which is just a pointer to some user provided data.
-A user defined array {\it UserArray} is created and bound to 
-the array {\it Alibrary} to take advanatage of the functionality provided 
-by the library.
-When bound array element migrated, the {\it data} pointer in {\it UserArray}
-is re-allocated in {\it pup()}, thus {\it UserArray} is responsible to refresh
-the pointer {\it dest} stored in {\it Alibrary}.
-
-\begin{alltt}
-class Alibrary: public CProxy_Alibrary \{
-public:
-  ...
-  void set_ptr(double *ptr) \{ dest = ptr; \}
-  virtual void pup(PUP::er &p);
-private:
-  double *dest;           // point to user data in user defined bound array
-\};
-
-class UserArray: public CProxy_UserArray \{
-public:
-  virtual void pup(PUP::er &p) \{
-                p|len;
-                if(p.isUnpacking()) \{ 
-                  data = new double[len];
-                  Alibrary *myfellow = AlibraryProxy(thisIndex).ckLocal();
-                  myfellow->set_ptr(data);    // refresh data in bound array
-                \}
-                p(data, len);
-  \}
-private:
-  CProxy_Alibrary  AlibraryProxy;   // proxy to my bound array
-  double *data;          // user allocated data pointer
-  int len;
-\};
-\end{alltt}
-
-
-\subsubsection{Advanced Array Creation: Dynamic Insertion}
-
-\label{dynamic_insertion}
-
-In addition to creating initial array elements using ckNew,
-you can also
-create array elements during the computation.
-
-You insert elements into the array by indexing the proxy
-and calling insert.  The insert call optionally takes 
-parameters, which are passed to the constructor; and a
-processor number, where the element will be created.
-Array elements can be inserted in any order from 
-any processor at any time.  Array elements need not 
-be contiguous.
-
-If using \kw{insert} to create all the elements of the array,
-you must call \kw{CProxy\_Array::doneInserting} before using
-the array.
-
-\begin{alltt}
-//In the .C file:
-int x,y,z;
-CProxy_A1 a1=CProxy_A1::ckNew();  //Creates a new, empty 1D array
-for (x=...) \{
-   a1[x  ].insert(\uw{parameters});  //Bracket syntax
-   a1(x+1).insert(\uw{parameters});  // or equivalent parenthesis syntax
-\}
-a1.doneInserting();
-
-CProxy_A2 a2=CProxy_A2::ckNew();   //Creates 2D array
-for (x=...) for (y=...)
-   a2(x,y).insert(\uw{parameters});  //Can't use brackets!
-a2.doneInserting();
-
-CProxy_A3 a3=CProxy_A3::ckNew();   //Creates 3D array
-for (x=...) for (y=...) for (z=...)
-   a3(x,y,z).insert(\uw{parameters});
-a3.doneInserting();
-
-CProxy_AF aF=CProxy_AF::ckNew();   //Creates user-defined index array
-for (...) \{
-   aF[CkArrayIndexFoo(...)].insert(\uw{parameters}); //Use brackets...
-   aF(CkArrayIndexFoo(...)).insert(\uw{parameters}); //  ...or parenthesis
-\}
-aF.doneInserting();
-
-\end{alltt}
-
-The \kw{doneInserting} call starts the reduction manager (see ``Array
-Reductions'') and load balancer (see ~\ref{lbFramework})-- since
-these objects need to know about all the array's elements, they
-must be started after the initial elements are inserted.
-You may call \kw{doneInserting} multiple times, but only the first
-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.
-
-If you do not specify one, the system will choose a procesor to 
-create an array element on based on the current map object.
-
-
-
-\subsubsection{Advanced Array Creation: Demand Creation}
-
-Normally, invoking an entry method on a nonexistant array
-element is an error.  But if you add the attribute
-\index{createhere} \index{createhome}
-\kw{[createhere]} or \kw{[createhome]} to an entry method,
- the array manager will 
-``demand create'' a new element to handle the message.  
-
-With \kw{[createhome]}, the new element
-will be created on the home processor, which is most efficient when messages for
-the element may arrive from anywhere in the machine. With \kw{[createhere]},
-the new element is created on the sending processor, which is most efficient
-if when messages will often be sent from that same processor.
-
-The new element is created by calling its default (taking no
-paramters) constructor, which must exist and be listed in the .ci file.
-A single array can have a mix of demand-creation and
-classic entry methods; and demand-created and normally 
-created elements.
-
-
-
-\subsubsection{User-defined array index type}
-
-\index{Array index type, user-defined}
-\charmpp{} array indices are arbitrary collections of integers.
-To define a new array index, you create an ordinary C++ class 
-which inherits from \kw{CkArrayIndex} and sets the ``nInts'' member
-to the length, in integers, of the array index.
-
-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{alltt}
-#include <charm++.h>
-class CkArrayIndexFoo:public CkArrayIndex \{
-    Foo f;
-public:
-    CkArrayIndexFoo(const Foo \&in) 
-    \{
-        f=in;
-        nInts=sizeof(f)/sizeof(int);
-    \}
-    //Not required, but convenient: cast-to-foo operators
-    operator Foo &() \{return f;\}
-    operator const Foo &() const \{return f;\}
-\};
-\end{alltt}
-
-Note that \uw{Foo}'s size must be an integral number of integers--
-you must pad it with zero bytes if this is not the case.
-Also, \uw{Foo} must be a simple class-- it cannot contain 
-pointers, have virtual functions, or require a destructor.
-Finally, there is a \charmpp\ configuration-time option called
-CK\_ARRAYINDEX\_MAXLEN \index{CK\_ARRAYINDEX\_MAXLEN} 
-which is the largest allowable number of 
-integers in an array index.  The default is 3; but you may 
-override this to any value by passing ``-DCK\_ARRAYINDEX\_MAXLEN=n'' 
-to the \charmpp\ build script as well as all user code. Larger 
-values will increase the size of each message.
-
-You can then declare an array indexed by \uw{Foo} objects with
-
-\begin{alltt}
-//in the .ci file:
-array [Foo] AF \{ entry AF(); ... \}
-
-//in the .h file:
-class AF : public CBase\_AF
-\{ public: AF() \{\} ... \}
-
-//in the .C file:
-    Foo f;
-    CProxy_AF a=CProxy_AF::ckNew();
-    a[CkArrayIndexFoo(f)].insert();
-    ...
-\end{alltt}
-
-Note that since our CkArrayIndexFoo constructor is not declared
-with the explicit keyword, we can equivalently write the last line as:
-
-\begin{alltt}
-    a[f].insert();
-\end{alltt}
-
-When you implement your array element class, as shown above you 
-can inherit from \kw{CBase}\_\uw{ClassName}, 
-a class templated by the index type \uw{Foo}. In the old syntax,
-you could also inherit directly from \kw{ArrayElementT}.
-The array index (an object of type \uw{Foo}) is then accessible as 
-``thisIndex''. For example:
-
-\begin{alltt}
-
-//in the .C file:
-AF::AF()
-\{
-    Foo myF=thisIndex;
-    functionTakingFoo(myF);
-\}
-\end{alltt}
-
-
-\subsubsection{Migratable Array Elements}
-
-\label{arraymigratable}
-Array objects can \index{migrate}migrate from one PE to another.
-For example, the load balancer (see section~\ref{lbFramework})
-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{alltt}
-//In the .h file:
-class A2 : public CBase\_A2 \{
-private: //My data members:
-    int nt;
-    unsigned char chr;
-    float flt[7];
-    int numDbl;
-    double *dbl;
-public:        
-    //...other declarations
-
-    virtual void pup(PUP::er \&p);
-\};
-
-//In the .C file:
-void A2::pup(PUP::er \&p)
-\{
-    CBase\_A2::pup(p); //<- MUST 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{alltt}
-
-Please note that if your object contains Structured Dagger code (see section ``Structured Dagger'') you must use the following syntax to correctly pup the object:
-
-\begin{alltt}
-class bar: public CBase\_bar \{
- private:
-    int a,b;
- public:
-    bar_SDAG_CODE 
-    ...other methods...
-
-    virtual void pup(PUP::er& p) \{
-      __sdag_pup(p);
-      ...pup other data here...
-    \}
-\};
-\end{alltt}
-
-See the \index{PUP} section ``PUP'' for more details on pup routines
-and the \kw{PUP::er} type.
-
-The system uses one pup routine to do both packing and unpacking by
-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 \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 section~\ref{lbarray}).
-
-To migrate your array element to another processor, the \charmpp{}
-runtime will:
-
-\begin{itemize}
-\item Call your \kw{ckAboutToMigrate} method
-\item Call your \uw{pup} method with a sizing \kw{PUP::er} to determine how 
-big a message it needs to hold your element.
-\item Call your \uw{pup} method again with a packing \kw{PUP::er} to pack 
-your element into a message.
-\item Call your element's destructor (killing off the old copy).
-\item Send the message (containing your element) across the network.
-\item Call your element's migration constructor on the new processor.
-\item Call your \uw{pup} method on with an unpacking \kw{PUP::er} to unpack 
-the element.
-\item Call your \kw{ckJustMigrated} method
-\end{itemize}
-
-Migration constructors, then, are normally empty-- all the unpacking
-and allocation of the data items is done in the element's \uw{pup} routine.
-Deallocation is done in the element destructor as usual.
-
-
-\subsubsection{Load Balancing Chare Arrays}
-
-see section~\ref{lbFramework}
-
-
-\subsubsection{Local Access}
-
-\experimental{}
-\index{ckLocal for arrays}
-\label{ckLocal for arrays}
-You can get direct access to a local array element using the
-proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
-to the element if it exists on the local processor; and NULL if
-the element does not exist or is on another processor.
-
+The data to be reduced comes from a call to the member \kw{contribute} 
+method:
 \begin{alltt}
-A1 *a=a1[i].ckLocal();
-if (a==NULL) //...is remote-- send message
-else //...is local-- directly use members and methods of a
+void contribute(int nBytes, const void *data, CkReduction::reducerType type);
 \end{alltt}
 
-Note that if the element migrates or is deleted, any pointers 
-obtained with \kw{ckLocal} are no longer valid.  It is best,
-then, to either avoid \kw{ckLocal} or else call \kw{ckLocal} 
-each time the element may have migrated; e.g., at the start 
-of each entry method.
-
-
-\subsubsection{Array Section}
-
-\experimental{}
-\label{array section}
-
-\charmpp{} supports array section which is a subset of array 
-elements in a chare array. \charmpp{} also supports array sections
-which are a subset of array elements in multiple chare arrays of the
-same type \ref{cross array section}.
-A special proxy for an array section can be created given a list of array
-indexes of elements.
-Multicast operations are directly supported in array section proxy with
-an unoptimized direct-sending implementation.
-Section reduction is not directly supported by the section proxy. 
-However, an optimized section multicast/reduction 
-library called ''CkMulticast'' is provided as a separate library module,
-which can be plugged in as a delegation of a section proxy for performing
-section-based multicasts and reductions. 
-
-For each chare array "A" declared in a ci file, a section proxy 
-of type "CProxySection\_A" is automatically generated in the decl and def 
-header files. 
-In order to create an array section, a user needs to provide array indexes 
-of all the array section members.
-You can create an array section proxy in your application by 
-invoking ckNew() function of the CProxySection.
-For example, for a 3D array:
+This call contributes \kw{nBytes} bytes starting at \kw{data} to the
+reduction \kw{type} (see reduction types, below).  Unlike sending a
+message, you may use \kw{data} after the call to \kw{contribute}.  All
+members of the chare array or group must call \kw{contribute}, and all of them must use the same
+reduction type.  
 
-\begin{alltt}
-  CkVec<CkArrayIndex3D> elems;    // add array indices
-  for (int i=0; i<10; i++)
-    for (int j=0; j<20; j+=2)
-      for (int k=0; k<30; k+=2)
-         elems.push_back(CkArrayIndex3D(i, j, k));
-  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems.getVec(), elems.size());
-\end{alltt}
+When you create a new chare array element, it is expected
+to contribute to the next reduction not already in progress on that
+processor.  The
+reduction will complete properly even if elements are migrated
+or deleted during the reduction. 
 
-Alternatively, one can do the same thing by providing [lbound:ubound:stride] 
-for each dimension:
+For example, if we want to sum each array/group member's single integer myInt, 
+we would use:
 
 \begin{alltt}
-  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, 0, 9, 1, 0, 19, 2, 0, 29, 2);
+    // Inside any member method
+    int myInt=get_myInt();
+    contribute(sizeof(int),\&myInt,CkReduction::sum_int);
 \end{alltt}
 
-The above codes create a section proxy that contains array elements of 
-[0:9, 0:19:2, 0:29:2].
-
-For user-defined array index other than CkArrayIndex1D to CkArrayIndex6D,
-one needs to use the generic array index type: CkArrayIndex.
+The built-in reduction types (see below) can also handle arrays of
+numbers.  For example, if each element of a chare array has a pair of
+doubles \uw{forces}[2], the corresponding elements of which are to be added across
+all elements, from each element call:
 
 \begin{alltt}
-  CkArrayIndex *elems;    // add array indices
-  int numElems;
-  CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems, numElems);
+    double forces[2]=get_my_forces();
+    contribute(2*sizeof(double),forces,CkReduction::sum_double);
 \end{alltt}
 
-Once you have the array section proxy, you can do multicast to all the 
-section members, or send messages to one member using its index that
-is local to the section, like these:
+This will result in a {\tt double} array of 2 elements, the first of which
+contains the sum of all \uw{forces}[0] values, with the second element 
+holding the sum of all \uw{forces}[1] values of the chare array elements.
 
-\begin{alltt}
-  CProxySection_Hello proxy;
-  proxy.someEntry(...)          // multicast
-  proxy[0].someEntry(...)       // send to the first element in the section.
-\end{alltt}
+Note that since C++ arrays (like \uw{forces}[2]) are already pointers, we 
+don't use \&\uw{forces}.
 
-You can move the section proxy in a message to another processor, and still 
-safely invoke the entry functions to the section proxy.
+Reductions do not have to specify commutative-associative operations on data;
+they can also be used to signal the fact that all array/group members
+have reached a certain synchronization point. In this case, a simpler version
+of contribute may be used:
 
-In the multicast example above, for a section with k members, total number 
-of k messages will be sent to all the memebers, which is considered 
-inefficient when several members are on a same processor, in which 
-case only one message needs to be sent to that processor and delivered to
-all section members on that processor locally. To support this optimization,
-a separate library called CkMulticast is provided. This library also supports
-section based reduction.
-
-Note: Use of the bulk array constructor (dimensions given in the CkNew
-or CkArrayOptions rather than individual insertion) will allow
-construction to race ahead of several other startup procedures, this
-creates some limitation on the construction delegation and use of
-array section proxies.  For safety, array sections should be
-created in a post constructor entry method.
-
-
-\label {array_section_multicast}
-
-
-To use the library, you need to compile and install CkMulticast library and 
-link your applications against the library using -module:
+%Sometimes it is not important the data to be reduced, but only the fact that all
+%elements have reached a synchronization point. In this case a simpler version of
+%contribute can be used:
 
 \begin{alltt}
-  # compile and install the CkMulticast library, do this only once
-  cd charm/net-linux/tmp
-  make multicast
-
-  # link CkMulticast library using -module when compiling application
-  charmc  -o hello hello.o -module CkMulticast -language charm++ 
+    contribute();
 \end{alltt}
 
-CkMulticast library is implemented using delegation(Sec. ~\ref{delegation}). 
-A special ''CkMulticastMgr'' Chare Group is created as a 
-deletegation for section multicast/reduction - all the messages sent
-by the section proxy will be passed to the local delegation branch.
-
-To use the CkMulticast delegation, one needs to create the CkMulticastMgr Group 
-first, and then setup the delegation relationship between the section proxy and 
-CkMulticastMgr Group. 
-One only needs to create one CkMulticastMgr Group globally.
-CkMulticastMgr group can serve all multicast/reduction delegations
-for different array sections in an application:
+In all cases, the result of the reduction operation is passed to the {\em reduction
+client}.  Many different kinds of reduction clients can be used, as
+explained below (Section~\ref{reductionClients}).
 
-\begin{alltt}
-  CProxySection_Hello sectProxy = CProxySection_Hello::ckNew(...);
-  CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew();
-  CkMulticastMgr *mCastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
+\paragraph{Typed Reductions}
 
-  sectProxy.ckSectionDelegate(mCastGrp);  // initialize section proxy
-
-  sectProxy.someEntry(...)           //multicast via delegation library as before
-\end{alltt}
+\label{typed_reductions}
 
-By default, CkMulticastMgr group builds a spanning tree for multicast/reduction
-with a factor of 2 (binary tree).
-One can specify a different factor when creating a CkMulticastMgr group.
+Typically the client entry method of a reduction takes a single argument of
+type CkReductionMsg. However, by giving an entry method the
+\kw{reductiontarget} attribute in the {\tt .ci} file, you can instead use entry methods that take
+arguments of the same type as specified by the {\em contribute} call.  
+When creating a callback to the
+reduction target, the entry method index is generated by 
+{\tt CkReductionTarget(ChareClass, method\_name)} 
+instead of {\tt CkIndex\_ChareClass::method\_name(...)}.
 For example,
+the code for a typed reduction that yields an {\tt int}, would look like this:
 
 \begin{alltt}
-  CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew(3);   // factor is 3
-\end{alltt}
-
-Note, to use CkMulticast library, all multicast messages must inherit from 
-CkMcastBaseMsg, as the following.
-Note that CkMcastBaseMsg must come first, this is IMPORTANT for CkMulticast 
-library to retrieve section information out of the message.
-
-
-\begin{alltt}
-class HiMsg : public CkMcastBaseMsg, public CMessage_HiMsg
-\{
-public:
-  int *data;
-\};
-\end{alltt}
-
-Due to this restriction, you need to define message explicitly for multicast 
-entry functions and no parameter marshalling can be used for multicast with 
-CkMulticast library.
+  // In the .ci file...
+  entry [reductiontarget] void done(int result);
 
-\paragraph{Array Section Reduction} 
+  // In some .cc file: 
+  // Create a callback that invokes the typed reduction client
+  CkCallback cb(CkReductionTarget(Driver,done), driverProxy);
 
-Since an array element can be members for multiple array sections, 
-there has to be a way for each array element to tell for which array
-section it wants to contribute. For this purpose, a data structure 
-called ''CkSectionInfo'' is created by CkMulticastMgr for each 
-array section that the array element belongs to.
-When doing section reduction, the array element needs to pass the 
-\kw{CkSectionInfo} as a parameter in the \kw{contribute()}. 
-The \kw{CkSectionInfo} can be retrieved
-from a message in a multicast entry function using function call 
-\kw{CkGetSectionInfo}:
+  // Contribution to the reduction...
+  contribute(sizeof(int), &intData, CkReduction::sum_int, cb);
 
-\begin{alltt}
-  CkSectionInfo cookie;
-
-  void SayHi(HiMsg *msg)
+  // Definition of the reduction client...
+  void Driver::done(int result) 
   \{
-    CkGetSectionInfo(cookie, msg);     // update section cookie every time
-    int data = thisIndex;
-    mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie);
+    CkPrintf("Reduction value: \%d", result);
   \}
 \end{alltt}
 
-Note that the cookie cannot be used as a one-time local variable in the 
-function, the same cookie is needed for the next contribute. This is 
-because cookie includes some context sensive information for example the 
-reduction counter. Function \kw{CkGetSectionInfo()} only update some part 
-of the data in cookie, not creating a brand new one.
-
-Similar to array reduction, to use section based reduction, a reduction
-client CkCallback object need to be created. You may pass the client callback 
-as an additional parameter to \kw{contribute}. If different contribute calls 
-pass different callbacks, some (unspecified, unreliable) callback will be 
-chosen for use. See the followin example:
-
-\begin{alltt}
-    CkCallback cb(CkIndex_myArrayType::myReductionEntry(NULL),thisProxy); 
-    mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie, cb);
-\end{alltt}
-
-If no member passes a callback to contribute, the reduction will use the 
-default callback. You set the default callback for an array section using the 
-\kw{setReductionClient} call by the section root member. A 
-{\bf CkReductionMsg} message will be passed to this callback, which 
-must delete the message when done.
-
-\begin{alltt}
-  CProxySection_Hello sectProxy;
-  CkMulticastMgr *mcastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
-  mcastGrp->setReductionClient(sectProxy, new CkCallback(...));
-\end{alltt}
-
-Same as in array reduction, users can use built-in reduction 
-types(Section~\ref{builtin_reduction}) or define his/her own reducer functions
-(Section~\ref{new_type_reduction}).
-
-\paragraph{Array section multicast/reduction when migration happens}
-
-Using multicast/reduction, you don't need to worry about array migrations.
-When migration happens, array element in the array section can still use 
-the \kw{CkSectionInfo} it stored previously for doing reduction. 
-Reduction messages will be correctly delivered but may not be as efficient 
-until a new multicast spanning tree is rebuilt internally 
-in \kw{CkMulticastMgr} library. 
-When a new spanning tree is rebuilt, a updated \kw{CkSectionInfo} is 
-passed along with a multicast message, 
-so it is recommended that 
-\kw{CkGetSectionInfo()} function is always called when a multicast 
-message arrives (as shown in the above SayHi example).
-
-In case when a multicast root migrates, one needs to reconstruct the 
-spanning tree to get optimal performance. One will get the following
-warning message if not doing so:
-"Warning: Multicast not optimized after multicast root migrated."
-In current implementation, user needs to initiate the rebuilding process
-like:
-
-\begin{alltt}
-void Foo::pup(PUP::er & p) {
-    // if I am multicast root and it is unpacking
-   if (ismcastroot && p.isUnpacking()) {
-      CProxySection_Foo   fooProxy;    // proxy for the section
-      CkMulticastMgr *mg = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
-      mg->resetSection(fooProxy);
-        // you may want to reset reduction client to root
-      CkCallback *cb = new CkCallback(...);
-      mg->setReductionClient(mcp, cb);
-   }
-}
-\end{alltt}
-
-\paragraph{Cross Array Sections}
-
-
-\experimental{}
-\label{cross array section}
-
-Cross array sections contain elements from multiple arrays.
-Construction and use of cross array sections is similar to normal
-array sections with the following restrictions.  
-
-\begin{itemize}
-
-\item Arrays in a section my all be of the same type.
-
-\item Each array must be enumerated by array ID
-
-\item The elements within each array must be enumerated explicitly
-
-\item No existing modules currently support delegation of cross
-  section proxies.  Therefore reductions are not currently supported.
-
-\end{itemize}
-
-Note: cross section logic also works for groups with analogous characteristics.
-
-Given three arrays declared thusly:
-
-\begin{alltt}
-         CkArrayID *aidArr= new CkArrayID[3];
-         CProxy\_multisectiontest\_array1d *Aproxy= new CProxy\_multisectiontest\_array1d[3];
-         for(int i=0;i<3;i++)
-           \{
-             Aproxy[i]=CProxy\_multisectiontest\_array1d::ckNew(masterproxy.ckGetGroupID(),ArraySize);   
-             aidArr[i]=Aproxy[i].ckGetArrayID();
-           \}
-\end{alltt}
-
-One can make a section including the  lower half elements of all three
-arrays as follows:
-
-\begin{alltt}
-         int aboundary=ArraySize/2;
-         int afloor=aboundary;
-         int aceiling=ArraySize-1;
-         int asectionSize=aceiling-afloor+1;
-         // cross section lower half of each array
-         CkArrayIndex **aelems= new CkArrayIndex*[3];
-         aelems[0]= new CkArrayIndex[asectionSize];
-         aelems[1]= new CkArrayIndex[asectionSize];
-         aelems[2]= new CkArrayIndex[asectionSize];
-         int *naelems=new int[3];
-         for(int k=0;k<3;k++)
-           \{
-             naelems[k]=asectionSize;
-             for(int i=afloor,j=0;i<=aceiling;i++,j++)
-               aelems[k][j]=CkArrayIndex1D(i);
-           \}
-         CProxySection\_multisectiontest\_array1d arrayLowProxy(3,aidArr,aelems,naelems);
-\end{alltt}
-
-
-
-The resulting cross section proxy, as in the example \uw{arrayLowProxy},
-can then be used for multicasts in the same way as a normal array
-section.
-
-Note: For simplicity the example has all arrays and sections of uniform
-size.  The size of each array and the number of elements in each array
-within a section can all be set independently.
-
+This will also work for arrays of data elements, and for any user-defined type with a PUP method
+(see ~\ref{sec:pup}). If you know that the reduction will yield a particular
+number of elements, say 3 {\tt int}s, you can also specify a reduction target which
+takes 3 {\tt int}s and it will be invoked correctly. 
 
diff --git a/doc/charm++/credits.tex b/doc/charm++/credits.tex
new file mode 100644 (file)
index 0000000..1eee56c
--- /dev/null
@@ -0,0 +1,101 @@
+\section{History}
+
+The {\sc Charm} software was developed as a group effort of the Parallel
+Programming Laboratory at the University of Illinois at Urbana-Champaign.
+Researchers at the Parallel Programming Laboratory keep \charmpp\ updated for
+the new machines, new programming paradigms, and for supporting and simplifying
+development of emerging applications for parallel processing.  The earliest
+prototype, Chare Kernel(1.0), was developed in the late eighties. It consisted
+only of basic remote method invocation constructs available as a library.  The
+second prototype, Chare Kernel(2.0), a complete re-write with major design
+changes.  This included C language extensions to denote Chares, messages and
+asynchronous remote method invocation.  {\sc Charm}(3.0) improved on this
+syntax, and contained important features such as information sharing
+abstractions, and chare groups (called Branch Office Chares).  {\sc Charm}(4.0)
+included \charmpp\ and was released in fall 1993.  \charmpp\ in its initial
+version consisted of syntactic changes to \CC\ and employed a special
+translator that parsed the entire \CC\ code while translating the syntactic
+extensions.  {\sc Charm}(4.5)  had a major change that resulted from a
+significant shift in the research agenda of the Parallel Programming
+Laboratory. The message-driven runtime system code of the \charmpp\ was
+separated from the actual language implementation, resulting in an
+interoperable parallel runtime system called {\sc
+Converse}. The \charmpp\ runtime system was
+retargetted on top of {\sc Converse}, and popular programming paradigms such as
+MPI and PVM were also implemented on {\sc Converse}. This allowed
+interoperability between these paradigms and \charmpp. This release also
+eliminated the full-fledged \charmpp\ translator by replacing syntactic
+extensions to \CC\ with \CC\ macros, and instead contained a small language and
+a translator for describing the interfaces of \charmpp\ entities to the runtime
+system.  This version of \charmpp, which, in earlier releases was known as {\em
+Interface Translator \charmpp}, is the default version of \charmpp\ now, and
+hence referred simply as {\bf \charmpp}.  In early 1999, the runtime system of
+\charmpp\ 
+%was formally named the Charm Kernel, and 
+was rewritten in \CC.
+Several new features were added. The interface language underwent significant
+changes, and the macros that replaced the syntactic extensions in original
+\charmpp, were replaced by natural \CC\ constructs. Late 1999, and early
+2000 reflected several additions to \charmpp{}, when a load balancing
+framework and migratable objects were added to \charmpp{}.
+
+\section {Acknowledgements}
+
+The Charm software was developed as a
+group effort.  The earliest prototype, Chare Kernel(1.0), was
+developed by Wennie Shu and Kevin Nomura working with Laxmikant
+Kale.  The second prototype, Chare Kernel(2.0), a complete
+re-write with major design changes, was developed by a team
+consisting of Wayne Fenton, Balkrishna Ramkumar, Vikram Saletore,
+Amitabh B. Sinha and Laxmikant Kale. The translator for Chare
+Kernel(2.0) was written by Manish Gupta.  Charm(3.0), with
+significant design changes, was developed by a team consisting of
+Attila Gursoy, Balkrishna Ramkumar, Amitabh B.  Sinha and
+Laxmikant Kale, with a new translator written by Nimish Shah.  The
+\charmpp\ implementation was done by Sanjeev Krishnan.  Charm(4.0)
+included \charmpp\ and was released in fall 1993.  Charm(4.5) was
+developed by Attila Gursoy, Sanjeev Krishnan, Milind Bhandarkar,
+Joshua Yelon, Narain Jagathesan and Laxmikant Kale.  Charm(4.8),
+developed by the same team included Converse, a parallel runtime
+system that allows interoperability among modules written using
+different paradigms within a single application. \charmpp\ runtime
+system was re-targetted at Converse. Syntactic extensions in
+\charmpp\ were dropped, and a simple interface translator was
+developed (by Sanjeev Krishnan and Jay DeSouza) that, along with
+the \charmpp\ runtime, became the \charmpp\ language.  Charm
+(5.4R1) included the following: a complete rewrite of the
+\charmpp\ runtime system (using \CC) and the interface translator
+(done by Milind Bhandarkar), several new features such as Chare
+Arrays (developed by Robert Brunner and Orion Lawlor), various
+libraries (written by Terry Wilmarth, Gengbin Zheng, Laxmikant
+Kale, Zehra Sura, Milind Bhandarkar, Robert Brunner, and Krishnan
+Varadarajan.) A coordination language ``Structured Dagger'' was
+been implemented on top of \charmpp\ (Milind Bhandarkar), dynamic
+seed-based load balancing (Terry Wilmarth and Joshua Yelon), a
+client-server interface for Converse programs, and debugging
+support by Parthasarathy Ramachandran, Jeff Wright, and Milind
+Bhandarkar, Projections, the performance visualization and
+analysis tool, was redesigned and rewritten using Java by Michael
+Denardo. The test suite for \charmpp\ was developed by Michael
+Lang, Jackie Wang, and Fang Hu. Converse was been ported to ASCI
+Red (Joshua Yelon), Cray T3E (Robert Brunner), and SGI Origin2000
+(Milind Bhandarkar). For the current version Charm 6.0 (R1),
+Converse has been ported to new platforms including BlueGene/[LP]
+(Kumar, Huang, Bhatele), Cray XT3/4 (Zheng), Apple G5, Myrinet
+(Zheng), and Infiniband (Chakravorty).  Charm 6.0 introduces a
+dedicated no network SMP multicore Converse layer for stand-alone
+workstation experimenters (Zheng, Chakravorty, Kale, Jetley).
+Charm 6.0 also includes cross platform network topology aware
+chare placement for 3D tori and mesh networks (Kumar, Huang,
+Bhatele, Bohm). The test suite was extended for automated testing
+on all supported platforms by Gengbin Zheng.  The Projection tool
+was substantially improved by Chee Wai Lee and Isaac Dooley. The
+Control Point performance tuning framework was created by Isaac
+Dooley. Debugging support was enhanced with memory inspection
+features by Filippo Gioachin. The Charisma orchestration language
+was implemented on top of Charm++ by Chao Huang and Sanjay Kale.
+Sanjay Kale, Orion Lawlor, Gengbin Zheng, Terry Wilmarth, Filippo
+Gioachin, Sayantan Chakravorty, Chao Huang, David Kunzman, Isaac
+Dooley, Eric Bohm, Sameer Kumar, Chao Mei, Pritish Jetley, and
+Abhinav Bhatele, have been responsible for the changes to the
+system since the last release. 
index 45dfef88b1b7d5b17dec86e5b82359f1e555f656..4ef18ca0a53672c66425a37c641b2abbc0c4d25a 100644 (file)
@@ -1,31 +1,4 @@
-\subsection{Entry Methods}
-
-\label{entry}
-
-In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
-nodegroups communicate using remote method invocation.  These ``remote entry'' methods may either take marshalled parameters, described in the next section; or special objects called messages.  Messages are lower level, more efficient, more flexible, and more difficult to use than parameter marshalling.
-
-An entry method is always a part of a chare--
-there are no global entry methods in \charmpp{}.
-Entry methods are declared in the the interface file as:
-
-\begin{alltt}
-entry void \uw{Entry1}(\uw{parameters});
-\end{alltt}
-
-\uw{Parameters} is either a list of marshalled parameters,
-(e.g., ``int i, double x''), or a message description (e.g.,
-``MyMessage *msg'').  See section~\ref{marshalling} and
-section~\ref{messages} for details on these types of
-parameters.
-
-Entry methods typically do not return data-- in \CC, they have
-return type ``void''.  An entry method with the same name
-as its enclosing class is a constructor.  Constructors in \CC
-have no return type.  Finally, sync methods, described below,
-may return a message.
-
-\subsubsection{Entry Method Attributes}
+\subsection{Entry Method Attributes}
 
 \label{attributes}
 
index f6c5f343513ab86864aa9b02845ba7b22a8eef13..8c6978860bafb8c488cea40e44fb0fa83f5d09bf 100644 (file)
@@ -21,56 +21,86 @@ platforms.  Please see the \charmpp{}/\converse{} Installation and
 Usage \htmladdnormallink{Manual}{http://charm.cs.uiuc.edu/manuals/html/install/manual.html}
 for details about installing, compiling and running \charmpp\ programs.
 
-\subsection{Overview}
+\subsection{\charmpp\ Execution Model}
 
-\charmpp\ is an object oriented parallel language. What sets \charmpp\ apart
-from traditional programming models such as message passing and shared variable
-programming is that the execution model of \charmpp\ is message-driven.
-Therefore, computations in \charmpp\ are triggered based on arrival of
-associated messages. These computations in turn can fire off more messages to
-other (possibly remote) processors that trigger more computations on those
-processors.
+A \charmpp\ program consists of a number of \charmpp\ objects distributed
+across the available number of processors. Thus, the basic unit of parallel
+computation in \charmpp\ programs is the {\em chare}\index{chare}, a \charmpp\
+object that can be created on any available processor and can be accessed from
+remote processors.  A \index{chare}chare is similar to a process, an actor, an
+ADA task, etc.  \index{chare}Chares are created dynamically, and many chares
+may be active simultaneously.  Chares send \index{message}{\em messages} to one
+another to invoke methods asynchronously.  Conceptually, the system maintains a
+``work-pool'' consisting of seeds for new \index{chare}chares, and
+\index{message}messages for existing chares. The Charm++ runtime system ({\em
+Charm RTS}) may pick multiple items, non-deterministically, from this pool
+and execute them.  
 
-At the heart of any \charmpp\ program is a scheduler that repetitively chooses
-a message from the available pool of messages, and executes the computations
-associated with that message.
+Methods of a \index{chare}chare that can be remotely invoked are called
+\index{entry method}{\em entry} methods.  Entry methods may take marshalled
+parameters, or a pointer to a message object.  Since \index{chare}chares can
+be created on remote processors, obviously some constructor of a chare needs
+to be an entry method.  Ordinary entry methods\footnote{``Threaded'' or
+``synchronous'' methods are different.} are completely non-preemptive--
+\charmpp\ will never interrupt an executing method to start any other work,
+and all calls made are asynchronous.
 
-The programmer-visible entities in a \charmpp\ program are:
+\charmpp\ provides dynamic seed-based load balancing. Thus location (processor
+number) need not be specified while creating a remote \index{chare}chare. The
+Charm RTS will then place the remote chare on a least loaded processor. Thus
+one can imagine chare creation as generating only a seed for the new chare,
+which may {\em take root} on the most {\em fertile} processor. Charm RTS
+identifies a \index{chare}chare by a {\em ChareID}.  Since user code does not
+need to name a chares' processor, chares can potentially migrate from one
+processor to another.  (This behavior is used by the dynamic load-balancing
+framework for chare containers, such as arrays.)
 
-\begin{itemize}
-\item Concurrent Objects : called {\em chares}\footnote{
-      Chare (pronounced {\bf ch\"ar}, \"a as in c{\bf a}rt) is Old 
-      English for chore.
-      }
-\item Communication Objects : Messages
-\item Readonly data
-\end{itemize}
+Other \charmpp\ objects are collections of chares. They are: {\em
+chare-arrays}, \index{group}{\em chare-groups}, and \index{nodegroup}{\em
+chare-nodegroups}, referred to as {\em arrays}, {\em groups}, and {\em
+nodegroups} throughout this manual. An array is a collection of arbitrary
+number of migratable chares, indexed by some index type, and mapped to
+processors according to a user-defined map group. A group (nodegroup) is a
+collection of chares, one per processor (SMP node), that is addressed using
+a unique system-wide name.
 
-\charmpp\ starts a program by creating a single \index{chare} instance of each
-{\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.
+Every \charmpp\ program must have at least one \kw{mainchare}.  Each
+\kw{mainchare} is created by the system on processor 0 when the \charmpp\
+program starts up.  Execution of a \charmpp\ program begins with the Charm
+Kernel constructing all the designated \kw{mainchare}s.  For a \kw{mainchare} named X, execution starts at constructor X() or X(CkArgMsg *) which are equivalent.
+Typically, the
+\kw{mainchare} constructor starts the computation by creating arrays, other
+chares, and groups.  It can also be used to initialize shared \kw{readonly}
+objects.
 
-Each \index{chare}chare contains a number of \index{entry method}{\em entry
-methods}, which are methods that can be invoked from remote processors. The
-\charmpp\ runtime system needs to be explicitly told about these methods, via
-an {\em interface} in a separate file.  The syntax of this interface
-specification file is described in the later sections.
+The only method of communication between processors in \charmpp\ is
+asynchronous \index{entry method} entry method invocation on remote chares.
+For this purpose, Charm RTS needs to know the types of
+\index{chare}chares in the user program, the methods that can be invoked on
+these chares from remote processors, the arguments these methods take as
+input etc. Therefore, when the program starts up, these user-defined
+entities need to be registered with Charm RTS, which assigns a unique
+identifier to each of them. While invoking a method on a remote object,
+these identifiers need to be specified to Charm RTS. Registration of
+user-defined entities, and maintaining these identifiers can be cumbersome.
+Fortunately, it is done automatically by the \charmpp\ interface translator.
+The \charmpp\ interface translator generates definitions for {\em proxy}
+objects. A proxy object acts as a {\em handle} to a remote chare. One
+invokes methods on a proxy object, which in turn carries out remote method
+invocation on the chare.
 
-\charmpp\ provides system calls to asynchronously create remote \index{chare}
-chares and to asynchronously invoke entry methods on remote chares by sending
-\index{message} messages to those chares. This asynchronous
-\index{message}message passing is the basic interprocess communication
-mechanism in \charmpp. However, \charmpp\ also permits wide variations on this
-mechanism to make it easy for the programmer to write programs that adapt to
-the dynamic runtime environment.  These possible variations include
-prioritization (associating priorities with method invocations), conditional
-\index{message packing}message packing and unpacking (for reducing messaging
-overhead), \index{quiescence}quiescence detection (for detecting completion of
-some phase of the program), and dynamic load balancing (during remote object
-creation). In addition, several libraries are built on top of \charmpp\ that
-can simplify otherwise arduous parallel programming tasks.
+In addition, the \charmpp\ interface translator provides ways to enhance the
+basic functionality of Charm RTS using user-level threads and futures. These
+allow entry methods to be executed in separate user-level threads.  These
+\index{threaded} {\em threaded} entry methods may block waiting for data by
+making {\em synchronous} calls to remote object methods that return results in
+messages.
+
+\charmpp\ program execution is terminated by the \kw{CkExit} call.  Like the
+\kw{exit} system call, \kw{CkExit} never returns. The Charm RTS ensures
+that no more messages are processed and no entry methods are called after a
+\kw{CkExit}. \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.
 
 The following sections provide detailed information about various features of the
 \charmpp\ programming system.\footnote{For a description of the underlying design
@@ -85,41 +115,4 @@ philosophy please refer to the following papers :\\
     Proceedings of the Conference on Object Oriented Programming,
     Systems, Languages and Applications (OOPSLA), September 1993.
 }.
-\subsection{History}
 
-The {\sc Charm} software was developed as a group effort of the Parallel
-Programming Laboratory at the University of Illinois at Urbana-Champaign.
-Researchers at the Parallel Programming Laboratory keep \charmpp\ updated for
-the new machines, new programming paradigms, and for supporting and simplifying
-development of emerging applications for parallel processing.  The earliest
-prototype, Chare Kernel(1.0), was developed in the late eighties. It consisted
-only of basic remote method invocation constructs available as a library.  The
-second prototype, Chare Kernel(2.0), a complete re-write with major design
-changes.  This included C language extensions to denote Chares, messages and
-asynchronous remote method invocation.  {\sc Charm}(3.0) improved on this
-syntax, and contained important features such as information sharing
-abstractions, and chare groups (called Branch Office Chares).  {\sc Charm}(4.0)
-included \charmpp\ and was released in fall 1993.  \charmpp\ in its initial
-version consisted of syntactic changes to \CC\ and employed a special
-translator that parsed the entire \CC\ code while translating the syntactic
-extensions.  {\sc Charm}(4.5)  had a major change that resulted from a
-significant shift in the research agenda of the Parallel Programming
-Laboratory. The message-driven runtime system code of the \charmpp\ was
-separated from the actual language implementation, resulting in an
-interoperable parallel runtime system called {\sc
-Converse}. The \charmpp\ runtime system was
-retargetted on top of {\sc Converse}, and popular programming paradigms such as
-MPI and PVM were also implemented on {\sc Converse}. This allowed
-interoperability between these paradigms and \charmpp. This release also
-eliminated the full-fledged \charmpp\ translator by replacing syntactic
-extensions to \CC\ with \CC\ macros, and instead contained a small language and
-a translator for describing the interfaces of \charmpp\ entities to the runtime
-system.  This version of \charmpp, which, in earlier releases was known as {\em
-Interface Translator \charmpp}, is the default version of \charmpp\ now, and
-hence referred simply as {\bf \charmpp}.  In early 1999, the runtime system of
-\charmpp\ was formally named the Charm Kernel, and was rewritten in \CC.
-Several new features were added. The interface language underwent significant
-changes, and the macros that replaced the syntactic extensions in original
-\charmpp, were replaced by natural \CC\ constructs. Late 1999, and early
-2000 reflected several additions to \charmpp{}, when a load balancing
-framework and migratable objects were added to \charmpp{}.
index 01722746586c96c2076b771f39c51f4115400ef1..19156617b82492526601f5249850d02f1e020bff 100644 (file)
@@ -419,134 +419,6 @@ The instrument of CPU usage is left on.
 
 \end{enumerate}
 
-\subsubsection{Load Balancing Simulation}
-
-The simulation feature of load balancing framework allows the users to collect information
-about the compute wall/cpu time and communication of the chares during a particular run of
-the program and use this information to later test different load balancing strategies to
-see which one is suitable for the programs behaviour. Currently, this feature is supported only for
-the centralized load balancing strategies. For this, the load balancing framework
-accepts the following command line options:
-\begin{enumerate}
-\item {\em +LBDump StepStart}\\
-        This will dump the instrument/communication data collected by the load balancing framework
-       starting from the load balancing step {\em StepStart} into a file on the disk. The name of the file
-       is given by the {\em +LBDumpFile} option. The first step in the program is number 0. Negative
-       numbers will be converted to 0.
-\item {\em +LBDumpSteps StepsNo}\\
-        This option specifies the number of steps for which data will be dumped to disk. If omitted, default value is 1.
-       The program will exit after StepsNo files are dumped.
-\item {\em +LBDumpFile FileName}\\
-       This option specifies the base name of the file into which the load balancing data is dumped. If this
-       option is not specified, the framework uses the default file {\tt lbdata.dat}. Since multiple steps are allowed,
-       a number is appended to the filename in the form {\tt Filename.\#}; this applies to both dump and
-       simulation.
-\item {\em +LBSim StepStart}\\
-       This option instructs the framework to do the simulation during the first load balancing step.
-       When this option is specified, the load balancing data from the file specified in the {\em +LBDumpFile}
-       option, with the addition of the step number, will be read and this data
-       will be used for the load balancing. The program will print the results
-       of the balancing for a number of steps given by the {\em +LBSimSteps} option, and then will exit.
-\item {\em +LBSimSteps StepsNo}\\
-        This option has the same meaning of {\em +LBDumpSteps}, except that apply for the simulation mode.
-       Default value is 1.
-\item {\em +LBSimProcs}\\
-        This option may change the number of processors target of the load balancer strategy. It may be used to test
-       the load balancer in conditions where some processor crashes or someone becomes available. If this number is not
-       changed since the original run, starting from the second step file the program will print other additional
-       information about how the simulated load differs from the real load during the run (considering all
-       strategies that were applied while running). This may be used to test the validity of a load balancer
-       prediction over the reality. If the strategies used during run and simulation differ, the additional data
-       printed may not be useful.
-\end{enumerate}
-As an example, we can collect the data for a 1000 processor run of a program using:
-\begin{alltt}
-./charmrun pgm +p 1000 +balancer RandCentLB +LBDump 2 +LBDumpSteps 4 +LBDumpFile dump.dat
-\end{alltt}
-This will collect data on files data.dat.{2,3,4,5}. Then, we can use this data to observe various centralized strategies using:
-\begin{alltt}
-./charmrun pgm +balancer <Strategy to test> +LBSim 2 +LBSimSteps 4 +LBDumpFile dump.dat [+LBSimProcs 900]
-\end{alltt}
-
-\subsubsection{Future load predictor}
-
-When objects do not follow the assumption that the future workload will be the
-same as the past, the load balancer might not have the correct information to do
-a correct rebalancing job. To prevent this the user can provide a transition
-function to the load balancer to predict what will be the future workload, given
-the past, instrumented one. As said, the user might provide a specific class
-which inherits from {\tt LBPredictorFunction} and implement the appropriate functions. 
-Here is the abstract class:
-\begin{alltt}
-class LBPredictorFunction {
-public:
-  int num_params;
-  virtual void initialize_params(double *x);
-
-  virtual double predict(double x, double *params) =0;
-  virtual void print(double *params) {PredictorPrintf("LB: unknown model");};
-  virtual void function(double x, double *param, double &y, double *dyda) =0;
-};
-\end{alltt}
-\begin{itemize}
-\item {\tt initialize\_params} by default initializes the parameters randomly. If the user
-knows how they should be, this function can be reimplemented.
-\item {\tt predict} is the function the model implements. For example, if the function is
-$y=ax+b$, the method in the implemented class should be like:
-\begin{verbatim}
-double predict(double x, double *param) {return (param[0]*x + param[1]);}
-\end{verbatim}
-\item {\tt print} is a debugging function and it can be reimplemented to have a meaningful
-print of the learnt model
-\item {\tt function} is a function internally needed to learn the parameters, {\tt x} and
-{\tt param} are input, {\tt y} and {\tt dyda} are output (the computed function and
-all its derivatives with respect to the parameters, respectively).
-For the function in the example should look like:
-\begin{verbatim}
-void function(double x, double *param, double &y, double *dyda) {
-  y = predict(x, param);
-  dyda[0] = x;
-  dyda[1] = 1;
-}
-\end{verbatim}
-\end{itemize}
-Other than these function, the user should provide a constructor which must initialize
-{\tt num\_params} to the number of parameters the model has to learn. This number is
-the dimension of {\tt param} and {\tt dyda} in the previous functions. For the given
-example, the constructor is {\tt \{num\_params = 2;\}}.
-
-If the model behind the computation is not known, the user can leave the system to
-use a predefined default function.
-
-As seen, the function can have several parameters which will be learned during
-the execution of the program. For this, two parameters can be setup at command
-line to specify the learning behaviour:
-\begin{enumerate}
-\item {\em +LBPredictorWindow size}\\
-This parameter will specify how many statistics the load balancer will keep. 
-The greater this number is, the better the
-approximation of the workload will be, but more memory is required to store
-the intermediate information. The default is 20.
-\item {\em +LBPredictorDelay steps}\\
-This will tell how many load balancer steps to wait before considering the
-function parameters learnt and start using the mode. The load balancer will
-collect statistics for a {\em +LBPredictorWindow} steps, but it will start using
-the model as soon as {\em +LBPredictorDelay} information are collected. The
-default is 10.
-\end{enumerate}
-Moreover another flag can be set to enable the predictor from command line: {\em
-+LBPredictor}.\\
-Other than the command line options, there are some methods
-callable from user program to modify the predictor. These methods are:
-\begin{itemize}
-\item {\tt void PredictorOn(LBPredictorFunction *model);}
-\item {\tt void PredictorOn(LBPredictorFunction *model,int wind);}
-\item {\tt void PredictorOff();}
-\item {\tt void ChangePredictor(LBPredictorFunction *model);}
-\end{itemize}
-
-
 \subsubsection{Seed load balancers - load balancing Chares at creation time}
 
 \label{seedlb}
index c1146a3f2ecadf904cfe855f9d73eaa4031bb16d..1a50e8a15ad6f8a816b56543f74a5351d17a94e7 100644 (file)
   \providecommand{\lstset}[2][]{}
 \end{htmlonly}
 
-
-\title{The\\ \charmpp\\ Programming Language\\ Manual} \version{6.0
-  (Release 1)} \credits{ {\small The Charm software was developed as a
-    group effort.  The earliest prototype, Chare Kernel(1.0), was
-    developed by Wennie Shu and Kevin Nomura working with Laxmikant
-    Kale.  The second prototype, Chare Kernel(2.0), a complete
-    re-write with major design changes, was developed by a team
-    consisting of Wayne Fenton, Balkrishna Ramkumar, Vikram Saletore,
-    Amitabh B. Sinha and Laxmikant Kale. The translator for Chare
-    Kernel(2.0) was written by Manish Gupta.  Charm(3.0), with
-    significant design changes, was developed by a team consisting of
-    Attila Gursoy, Balkrishna Ramkumar, Amitabh B.  Sinha and
-    Laxmikant Kale, with a new translator written by Nimish Shah.  The
-    \charmpp\ implementation was done by Sanjeev Krishnan.  Charm(4.0)
-    included \charmpp\ and was released in fall 1993.  Charm(4.5) was
-    developed by Attila Gursoy, Sanjeev Krishnan, Milind Bhandarkar,
-    Joshua Yelon, Narain Jagathesan and Laxmikant Kale.  Charm(4.8),
-    developed by the same team included Converse, a parallel runtime
-    system that allows interoperability among modules written using
-    different paradigms within a single application. \charmpp\ runtime
-    system was re-targetted at Converse. Syntactic extensions in
-    \charmpp\ were dropped, and a simple interface translator was
-    developed (by Sanjeev Krishnan and Jay DeSouza) that, along with
-    the \charmpp\ runtime, became the \charmpp\ language.  Charm
-    (5.4R1) included the following: a complete rewrite of the
-    \charmpp\ runtime system (using \CC) and the interface translator
-    (done by Milind Bhandarkar), several new features such as Chare
-    Arrays (developed by Robert Brunner and Orion Lawlor), various
-    libraries (written by Terry Wilmarth, Gengbin Zheng, Laxmikant
-    Kale, Zehra Sura, Milind Bhandarkar, Robert Brunner, and Krishnan
-    Varadarajan.) A coordination language ``Structured Dagger'' was
-    been implemented on top of \charmpp\ (Milind Bhandarkar), dynamic
-    seed-based load balancing (Terry Wilmarth and Joshua Yelon), a
-    client-server interface for Converse programs, and debugging
-    support by Parthasarathy Ramachandran, Jeff Wright, and Milind
-    Bhandarkar, Projections, the performance visualization and
-    analysis tool, was redesigned and rewritten using Java by Michael
-    Denardo. The test suite for \charmpp\ was developed by Michael
-    Lang, Jackie Wang, and Fang Hu. Converse was been ported to ASCI
-    Red (Joshua Yelon), Cray T3E (Robert Brunner), and SGI Origin2000
-    (Milind Bhandarkar). For the current version Charm 6.0 (R1),
-    Converse has been ported to new platforms including BlueGene/[LP]
-    (Kumar, Huang, Bhatele), Cray XT3/4 (Zheng), Apple G5, Myrinet
-    (Zheng), and Infiniband (Chakravorty).  Charm 6.0 introduces a
-    dedicated no network SMP multicore Converse layer for stand-alone
-    workstation experimenters (Zheng, Chakravorty, Kale, Jetley).
-    Charm 6.0 also includes cross platform network topology aware
-    chare placement for 3D tori and mesh networks (Kumar, Huang,
-    Bhatele, Bohm). The test suite was extended for automated testing
-    on all supported platforms by Gengbin Zheng.  The Projection tool
-    was substantially improved by Chee Wai Lee and Isaac Dooley. The
-    Control Point performance tuning framework was created by Isaac
-    Dooley. Debugging support was enhanced with memory inspection
-    features by Filippo Gioachin. The Charisma orchestration language
-    was implemented on top of Charm++ by Chao Huang and Sanjay Kale.
-    Sanjay Kale, Orion Lawlor, Gengbin Zheng, Terry Wilmarth, Filippo
-    Gioachin, Sayantan Chakravorty, Chao Huang, David Kunzman, Isaac
-    Dooley, Eric Bohm, Sameer Kumar, Chao Mei, Pritish Jetley, and
-    Abhinav Bhatele, have been responsible for the changes to the
-    system since the last release.  } }
-
 \begin{document}
 
+\title{The\\ \charmpp\\ Programming Language\\ Manual} \version{6.0
+  (Release 1)} \credits {  \hspace{0 in} }
 \maketitle
 
 \input{intro}
 
+\begin{titlepage}%
+ \rule{\textwidth}{3pt}
+ \vspace{\fill}
+ \begin{flushright}
+   \textsf{\Huge Basic Concepts \\}
+ \end{flushright}
+ \vspace{\fill}
+ \rule{\textwidth}{3pt}
+\end{titlepage}
+
 \input{overview}
 
-\section{The \charmpp\ Language}
+\section{Basic Concepts}
+
   \input{modules}      
-  \input{entry}
   \input{marshalling}  
-  \input{messages}
-  \input{order.tex}
   \input{chares}
-  \input{readonly}    
+  \input{readonly}
   \input{arrays}
+  \input{sdag}
+  \input{pup}
+  \input{loadb}
   \input{groups}
   \input{nodegroups}
-  \input{loadb}
+
+\begin{titlepage}%
+ \rule{\textwidth}{3pt}
+ \vspace{\fill}
+ \begin{flushright}
+   \textsf{\Huge Advanced Concepts \\}
+ \end{flushright}
+ \vspace{\fill}
+ \rule{\textwidth}{3pt}
+\end{titlepage}
+
+\section{Advanced Concepts}
+
+  \input{entry}
+  \input{messages}
+  \input{order.tex}
+  \input{advancedarrays}
+
+
   \input{advancedlb}
   \input{futures}
   \input{quiesce}
   \input{reductions}
   \input{callbacks}
-  \input{pup}
+  \input{advancedpup}
   \input{io}
   \input{othercalls}    
   \input{delegation}    
   \input{python}
 \input{inhertmplt}
 
-\input{msa.tex}
+
+% TO BE MOVED TO ITS OWN MANUAL
+%\input{msa.tex}
 
 \input{checkpoint}
 
 
 \appendix
 
-\input{sdag}
 
-\input{quickbigsim}
+% TO BE MOVED TO ITS OWN MANUAL
+%\input{quickbigsim}
 
 \input{further}
 
 \input{index}
 
+\input{credits}
+
 \end{document}
index d567f950649fa24f70c9b70f6552bc1e0d64be44..c9ce74a6279add69b14b11c5b87bd5a8042af0d0 100644 (file)
@@ -1,4 +1,31 @@
-\subsection{Parameter Marshalling}
+\subsection{Entry Methods}
+
+\label{entry}
+
+In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
+nodegroups communicate using remote method invocation.  These ``remote entry'' methods may either take marshalled parameters, described in the next section; or special objects called messages.  Messages are lower level, more efficient, more flexible, and more difficult to use than parameter marshalling.
+
+An entry method is always a part of a chare--
+there are no global entry methods in \charmpp{}.
+Entry methods are declared in the the interface file as:
+
+\begin{alltt}
+entry void \uw{Entry1}(\uw{parameters});
+\end{alltt}
+
+\uw{Parameters} is either a list of marshalled parameters,
+(e.g., ``int i, double x''), or a message description (e.g.,
+``MyMessage *msg'').  See section~\ref{marshalling} and
+section~\ref{messages} for details on these types of
+parameters.
+
+Entry methods typically do not return data-- in \CC, they have
+return type ``void''.  An entry method with the same name
+as its enclosing class is a constructor.  Constructors in \CC
+have no return type.  Finally, sync methods, described below,
+may return a message.
+
+\subsection{Entry Method Invocation}
 
 \label{marshalling}
 
index 9c715ff49e65fb619af7c13e9b3d4b24b86e6242..acb1baa003c3877a7cfb9015f04d75f919c070ef 100644 (file)
@@ -1,6 +1,5 @@
-\subsection{Modules}
 
-\subsubsection{Structure of a \charmpp\ Program}
+\subsection{Structure of a \charmpp\ Program}
 
 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
@@ -120,12 +119,12 @@ pgm: pgm.ci pgm.h pgm.C
 
 \end{alltt}
 
-\uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm Kernel starts
+\uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm RTS 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 the group returns immediately after directing Charm RTS to perform
+the actual creation and invocation.  Shortly after, the Charm RTS 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{PrintDone} method of \uw{HelloMain}. The \uw{PrintDone} method
index f858c051f4d28a1ac89d2fd2f5bd4618159b4e78..d4790ecf4c3d395e2220b90e8aad6bf35aa80027 100644 (file)
@@ -1,5 +1,54 @@
 \section{\charmpp{} Overview}
 
+\charmpp\ is an object oriented parallel language. What sets \charmpp\ apart
+from traditional programming models such as message passing and shared variable
+programming is that the execution model of \charmpp\ is message-driven.
+Therefore, computations in \charmpp\ are triggered based on arrival of
+associated messages. These computations in turn can fire off more messages to
+other (possibly remote) processors that trigger more computations on those
+processors.
+
+At the heart of any \charmpp\ program is a scheduler that repetitively chooses
+a message from the available pool of messages, and executes the computations
+associated with that message.
+
+The programmer-visible entities in a \charmpp\ program are:
+
+\begin{itemize}
+\item Concurrent Objects : called {\em chares}\footnote{
+      Chare (pronounced {\bf ch\"ar}, \"a as in c{\bf a}rt) is Old 
+      English for chore.
+      }
+\item Communication Objects : Messages
+\item Readonly data
+\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
+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
+\charmpp\ runtime system needs to be explicitly told about these methods, via
+an {\em interface} in a separate file.  The syntax of this interface
+specification file is described in the later sections.
+
+\charmpp\ provides system calls to asynchronously create remote \index{chare}
+chares and to asynchronously invoke entry methods on remote chares by sending
+\index{message} messages to those chares. This asynchronous
+\index{message}message passing is the basic interprocess communication
+mechanism in \charmpp. However, \charmpp\ also permits wide variations on this
+mechanism to make it easy for the programmer to write programs that adapt to
+the dynamic runtime environment.  These possible variations include
+prioritization (associating priorities with method invocations), conditional
+\index{message packing}message packing and unpacking (for reducing messaging
+overhead), \index{quiescence}quiescence detection (for detecting completion of
+some phase of the program), and dynamic load balancing (during remote object
+creation). In addition, several libraries are built on top of \charmpp\ that
+can simplify otherwise arduous parallel programming tasks.
+
 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 are encouraged to let us know the reasons, and features that you would
@@ -65,88 +114,6 @@ parameter marshalled.  This is now true of almost all objects in
 Charm++: the only exceptions being entire Chares (Array Elements,
 etc.) and, paradoxically, messages themselves.
 
-\subsection{\charmpp\ Execution Model}
-
-A \charmpp\ program consists of a number of \charmpp\ objects distributed
-across the available number of processors. Thus, the basic unit of parallel
-computation in \charmpp\ programs is the {\em chare}\index{chare}, a \charmpp\
-object that can be created on any available processor and can be accessed from
-remote processors.  A \index{chare}chare is similar to a process, an actor, an
-ADA task, etc.  \index{chare}Chares are created dynamically, and many chares
-may be active simultaneously.  Chares send \index{message}{\em messages} to one
-another to invoke methods asynchronously.  Conceptually, the system maintains a
-``work-pool'' consisting of seeds for new \index{chare}chares, and
-\index{message}messages for existing chares. The runtime system (called {\em
-Charm Kernel}) may pick multiple items, non-deterministically, from this pool
-and execute them.  
-
-Methods of a \index{chare}chare that can be remotely invoked are called
-\index{entry method}{\em entry} methods.  Entry methods may take marshalled
-parameters, or a pointer to a message object.  Since \index{chare}chares can
-be created on remote processors, obviously some constructor of a chare needs
-to be an entry method.  Ordinary entry methods\footnote{``Threaded'' or
-``synchronous'' methods are different.} are completely non-preemptive--
-\charmpp\ will never interrupt an executing method to start any other work,
-and all calls made are asynchronous.
-
-\charmpp\ provides dynamic seed-based load balancing. Thus location (processor
-number) need not be specified while creating a remote \index{chare}chare. The
-Charm Kernel will then place the remote chare on a least loaded processor. Thus
-one can imagine chare creation as generating only a seed for the new chare,
-which may {\em take root} on the most {\em fertile} processor. Charm Kernel
-identifies a \index{chare}chare by a {\em ChareID}.  Since user code does not
-need to name a chares' processor, chares can potentially migrate from one
-processor to another.  (This behavior is used by the dynamic load-balancing
-framework for chare containers, such as arrays.)
-
-Other \charmpp\ objects are collections of chares. They are: {\em
-chare-arrays}, \index{group}{\em chare-groups}, and \index{nodegroup}{\em
-chare-nodegroups}, referred to as {\em arrays}, {\em groups}, and {\em
-nodegroups} throughout this manual. An array is a collection of arbitrary
-number of migratable chares, indexed by some index type, and mapped to
-processors according to a user-defined map group. A group (nodegroup) is a
-collection of chares, one per processor (SMP node), that is addressed using
-a unique system-wide name.
-
-Every \charmpp\ program must have at least one \kw{mainchare}.  Each
-\kw{mainchare} is created by the system on processor 0 when the \charmpp\
-program starts up.  Execution of a \charmpp\ program begins with the Charm
-Kernel constructing all the designated \kw{mainchare}s.  For a \kw{mainchare} named X, execution starts at constructor X() or X(CkArgMsg *) which are equivalent.
-Typically, the
-\kw{mainchare} constructor starts the computation by creating arrays, other
-chares, and groups.  It can also be used to initialize shared \kw{readonly}
-objects.
-
-The only method of communication between processors in \charmpp\ is
-asynchronous \index{entry method} entry method invocation on remote chares.
-For this purpose, Charm Kernel needs to know the types of
-\index{chare}chares in the user program, the methods that can be invoked on
-these chares from remote processors, the arguments these methods take as
-input etc. Therefore, when the program starts up, these user-defined
-entities need to be registered with Charm Kernel, which assigns a unique
-identifier to each of them. While invoking a method on a remote object,
-these identifiers need to be specified to Charm Kernel. Registration of
-user-defined entities, and maintaining these identifiers can be cumbersome.
-Fortunately, it is done automatically by the \charmpp\ interface translator.
-The \charmpp\ interface translator generates definitions for {\em proxy}
-objects. A proxy object acts as a {\em handle} to a remote chare. One
-invokes methods on a proxy object, which in turn carries out remote method
-invocation on the chare.
-
-In addition, the \charmpp\ interface translator provides ways to enhance the
-basic functionality of Charm Kernel using user-level threads and futures. These
-allow entry methods to be executed in separate user-level threads.  These
-\index{threaded} {\em threaded} entry methods may block waiting for data by
-making {\em synchronous} calls to remote object methods that return results in
-messages.
-
-\charmpp\ program execution is terminated by the \kw{CkExit} call.  Like the
-\kw{exit} system call, \kw{CkExit} never returns. The Charm Kernel ensures
-that no more messages are processed and no entry methods are called after a
-\kw{CkExit}. \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.
-
-
 \subsection{Entities in \charmpp\ programs}
 
 This section describes various entities in a typical \charmpp\ program.
index e30ae60562fe7d0c62dfcfd7cfa2d256d722390b..896081e54440f06a56ffa047b9d7c151b88728e6 100644 (file)
@@ -261,525 +261,3 @@ as usual.
 
 
 
-\subsubsection{Dynamic Allocation}
-
-\label{sec:pupdynalloc}
-
-If your class has fields that are dynamically allocated, when unpacking
-these need to be allocated (in the usual way) before you pup them.
-Deallocation should be left to the class destructor as usual.
-
-\paragraph{No allocation}
-
-The simplest case is when there is no dynamic allocation.
-\begin{alltt}
-class keepsFoo : public mySuperclass \{
-private:
-    foo f; /* simple foo object*/
-public:
-    keepsFoo(void) \{ \}
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      p|f; // pup f's fields (calls f.pup(p);) 
-    \}
-    ~keepsFoo() \{ \}
-\};
-\end{alltt}
-
-\paragraph{Allocation outside pup}
-
-The next simplest case is when we contain a class 
-that is always allocated during our constructor,
-and deallocated during our destructor.  Then no allocation
-is needed within the pup routine.
-\begin{alltt}
-class keepsHeapFoo : public mySuperclass \{
-private:
-    foo *f; /*Heap-allocated foo object*/
-public:
-    keepsHeapFoo(void) \{
-      f=new foo;
-    \}
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      p|*f; // pup f's fields (calls f->pup(p))
-    \}
-    ~keepsHeapFoo() \{delete f;\}
-\};
-\end{alltt}
-
-\paragraph{Allocation during pup}
-
-If we need values obtained during the pup routine
-before we can allocate the class, we must 
-allocate the class inside the pup routine.
-Be sure to protect the allocation with ``if (p.isUnpacking())''.
-\begin{alltt}
-class keepsOneFoo : public mySuperclass \{
-private:
-    foo *f; /*Heap-allocated foo object*/
-public:
-    keepsOneFoo(...) \{f=new foo(...);\}
-    keepsOneFoo() \{f=NULL;\} /* pup constructor */
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      ...
-      if (p.isUnpacking()) /* must allocate foo now */
-         f=new foo(...);
-      p|*f;//pup f's fields
-    \}
-    ~keepsOneFoo() \{delete f;\}
-\};
-\end{alltt}
-
-\paragraph{Allocatable array}
-
-For example, if we keep an array of doubles,
-we need to know how many doubles there are 
-before we can allocate the array.  Hence we must
-first pup the array length, do our allocation,
-and then pup the array data.  We could allocate memory using 
-malloc/free or other allocators in exactly the same way.
-\begin{alltt}
-class keepsDoubles : public mySuperclass \{
-private:
-    int n;
-    double *arr;/*new'd array of n doubles*/
-public:
-    keepsDoubles(int n_) \{
-      n=n_;
-      arr=new double[n];
-    \}
-    keepsDoubles() \{ \} 
-    
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      p|n;//pup the array length n
-      if (p.isUnpacking())  arr=new double[n];
-      PUParray(p,arr,n); //pup data in the array
-    \}
-    
-    ~keepsDoubles() \{delete[] arr;\}
-\};
-\end{alltt}
-
-\paragraph{NULL object pointer}
-
-If our allocated object may be NULL, our allocation
-becomes much more complicated.  We must first check
-and pup a flag to indicate whether the object exists, 
-then depending on the flag, pup the object.
-\begin{alltt}
-class keepsNullFoo : public mySuperclass \{
-private:
-    foo *f; /*Heap-allocated foo object, or NULL*/
-public:
-    keepsNullFoo(...) \{ if (...) f=new foo(...);\}
-    keepsNullFoo() \{f=NULL;\}
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      int has_f=(f!=NULL);
-      p|has_f;
-      if (has_f) {
-        if (p.isUnpacking()) f=new foo;
-        p|*f;
-      } else {
-        f=NULL;
-      }
-    \}
-    ~keepsNullFoo() \{delete f;\}
-\};
-\end{alltt}
-
-This sort of code is normally much longer and more
-error-prone if split into the various packing/unpacking cases.
-
-\paragraph{Array of classes}
-
-An array of actual classes can be treated exactly the same way
-as an array of basic types.  PUParray will pup each 
-element of the array properly, calling the appropriate \verb.operator|..
-\begin{alltt}
-class keepsFoos : public mySuperclass \{
-private:
-    int n;
-    foo *arr;/*new'd array of n foos*/
-public:
-    keepsFoos(int n_) \{
-      n=n_;
-      arr=new foo[n];
-    \}
-    keepsFoos() \{ arr=NULL; \} 
-    
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      p|n;//pup the array length n
-      if (p.isUnpacking())  arr=new foo[n];
-      PUParray(p,arr,n); //pup each foo in the array
-    \}
-    
-    ~keepsFoos() \{delete[] arr;\}
-\};
-\end{alltt}
-
-
-\paragraph{Array of pointers to classes}
-
-An array of pointers to classes must handle each element
-separately, since the PUParray routine does not work with 
-pointers.  An ``allocate'' routine to set up the array
-could simplify this code.  More ambitious is to construct
-a ``smart pointer'' class that includes a pup routine.
-\begin{alltt}
-class keepsFooPtrs : public mySuperclass \{
-private:
-    int n;
-    foo **arr;/*new'd array of n pointer-to-foos*/
-public:
-    keepsFooPtrs(int n_) \{
-      n=n_;
-      arr=new foo*[n]; // allocate array
-      for (int i=0;i<n;i++) arr[i]=new foo(...); // allocate i'th foo
-    \}
-    keepsFooPtrs() \{ arr=NULL; \} 
-    
-    void pup(PUP::er &p) \{
-      mySuperclass::pup(p);
-      p|n;//pup the array length n
-      if (p.isUnpacking()) arr=new foo*[n]; // allocate array
-      for (int i=0;i<n;i++) \{
-        if (p.isUnpacking()) arr[i]=new foo(...); // allocate i'th foo
-        p|*arr[i];  //pup the i'th foo
-      \}
-    \}
-    
-    ~keepsFooPtrs() \{
-       for (int i=0;i<n;i++) delete arr[i];
-       delete[] arr;
-     \}
-\};
-\end{alltt}
-
-Note that this will not properly handle the case where
-some elements of the array are actually subclasses of foo,
-with virtual methods.  The PUP::able framework described
-in the next section can be helpful in this case.
-
-
-\subsubsection{Subclass allocation via PUP::able}
-
-\label{sec:pup::able}
-If the class \uw{foo} above might have been a subclass, instead of
-simply using \uw{new foo} above we would have had to allocate 
-an object of the appropriate subclass.  Since determining the
-proper subclass and calling the appropriate constructor yourself can be 
-difficult, the PUP framework provides a scheme for automatically
-determining and dynamically allocating subobjects of the appropriate type.
-
-Your superclass must inherit from \kw{PUP::able}, which provides 
-the basic machinery used to move the class.  
-A concrete superclass and all its concrete subclasses require these
-four features:
-
-\begin{itemize}
-\item A line declaring \kw{PUPable \uw{className};} in the .ci file.
-This registers the class's constructor.
-
-\item A call to the macro \kw{PUPable\_decl(\uw{className})} in the
-class's declaration, in the header file.  This adds a virtual 
-method to your class to allow \kw{PUP::able} to determine your class's type.
-
-\item A migration constructor---a constructor that takes \kw{CkMigrateMessage *}.
-This is used to create the new object on the receive side, immediately
-before calling the new object's \kw{pup} routine.
-
-\item A working, virtual \kw{pup} method.  You can omit this if your
-class has no data that needs to be packed.
-\end{itemize}
-
-An abstract superclass---a superclass that will never actually be 
-packed---only needs to inherit from \kw{PUP::able} and include a 
-\kw{PUPable\_abstract(\uw{className})} macro in their body.  For
-these abstract classes, the 
-.ci file, \kw{PUPable\_decl} macro, and constructor are not needed.
-
-For example, if \uw{parent} is a concrete superclass and \uw{child} its
-subclass,
-
-\begin{alltt}
-//In the .ci file:
-   PUPable parent;
-   PUPable child; //Could also have said ``PUPable parent, child;''
-
-//In the .h file:
-class parent : public PUP::able \{
-    ... data members ...
-public:
-    ... other methods ...
-    parent() \{...\}
-    
-    //PUP::able support: decl, migration constructor, and pup
-    PUPable\_decl(parent);  
-    parent(CkMigrateMessage *m) : PUP::able(m) \{\}
-    virtual void pup(PUP::er &p) \{
-        PUP::able::pup(p);//Call base class
-        ... pup data members as usual ...
-    \}  
-\};
-class child : public parent \{
-    ... more data members ...
-public:    ... more methods, possibly virtual ...
-    child() \{...\}
-    
-    //PUP::able support: decl, migration constructor, and pup
-    PUPable\_decl(child);  
-    child(CkMigrateMessage *m) : parent(m) \{\}
-    virtual void pup(PUP::er &p) \{
-        parent::pup(p);//Call base class
-        ... pup child's data members as usual ...
-    \}  
-\};
-
-\end{alltt}
-
-With these declarations, then, we can automatically 
-allocate and pup a pointer to a parent or child
-using the vertical bar \kw{PUP::er} syntax, which on the receive
-side will create a new object of the appropriate type:
-
-\begin{alltt}
-class keepsParent \{
-    parent *obj; //May actually point to a child class (or be NULL)
-public:
-    ...
-    ~keepsParent() \{
-        delete obj;
-    \}
-    void pup(PUP::er &p) 
-    \{
-        p|obj;
-    \}
-\};
-PUPmarshall(keepsParent);
-\end{alltt}
-
-This will properly pack, allocate, and unpack obj whether
-it is actually a parent or child object.  The child class 
-can use all the usual \CC\ features, such as virtual functions
-and extra private data.
-
-If obj is NULL when packed, it will be restored to NULL when unpacked.
-For example, if the nodes of a binary tree are \kw{PUP::able},
-one may write a recursive pup routine for the tree quite easily:
-
-\begin{alltt}
-// In the .ci file:
-    PUPable treeNode;
-
-// In the .h file
-class treeNode : public PUP::able \{
-    treeNode *left;//Left subtree
-    treeNode *right;//Right subtree
-    ... other fields ...
-public:
-    treeNode(treeNode *l=NULL, treeNode *r=NULL);
-    ~treeNode() \{delete left; delete right;\}
-    
-    // The usual PUP::able support:
-    PUPable\_decl(treeNode);
-    treeNode(CkMigrateMessage *m) : PUP::able(m) \{ left=right=NULL; \}
-    void pup(PUP::er &p) \{
-        PUP::able::pup(p);//Call base class
-        p|left;
-        p|right;
-        ... pup other fields as usual ...
-    \}
-\};
-\end{alltt}
-
-This same implementation will also work properly even if the tree's
-internal nodes are actually subclasses of treeNode.
-
-You may prefer to use the macros \kw{PUPable\_def(\uw{className})}
-and \kw{PUPable\_reg(\uw{className})} rather than using \kw{PUPable}
-in the .ci file.  \kw{PUPable\_def} provides routine definitions used
-by the \kw{PUP::able} machinery, and should be included in exactly one
-source file at file scope.  \kw{PUPable\_reg} registers this class
-with the runtime system, and should be executed exactly once per node 
-during program startup.
-
-Finally, a \kw{PUP::able} superclass like \uw{parent} above 
-must normally be passed around via a pointer or reference, because the object
-might actually be some subclass like \uw{child}.  Because
-pointers and references cannot be passed across processors,
-for parameter marshalling you must use the special templated 
-smart pointer classes \kw{CkPointer} and \kw{CkReference},
-which only need to be listed in the .ci file.
-
-A \kw{CkReference} is a read-only reference to a \kw{PUP::able} object---it
-is only valid for the duration of the method call.  A \kw{CkPointer}
-transfers ownership of the unmarshalled \kw{PUP::able} to the method, so the 
-pointer can be kept and the object used indefinitely.  
-
-For example, if the entry method \uw{bar} needs a \kw{PUP::able} \uw{parent}
-object for in-call processing, you would use a \kw{CkReference} like this:
-
-\begin{alltt}
-// In the .ci file:
-    entry void barRef(int x,CkReference<parent> p);
-
-// In the .h file:
-    void barRef(int x,parent &p) \{
-      // can use p here, but only during this method invocation
-    \}
-\end{alltt}
-
-If the entry method needs to keep its parameter, use a \kw{CkPointer} like this:
-\begin{alltt}
-// In the .ci file:
-    entry void barPtr(int x,CkPointer<parent> p);
-
-// In the .h file:
-    void barPtr(int x,parent *p) \{
-      // can keep this pointer indefinitely, but must eventually delete it
-    \}
-\end{alltt}
-
-Both \kw{CkReference} and \kw{CkPointer} are read-only from the send 
-side---unlike messages, which are consumed when sent, the same object 
-can be passed to several parameter marshalled entry methods.
-In the example above, we could do:
-
-\begin{alltt}
-   parent *p=new child;
-   someProxy.barRef(x,*p);
-   someProxy.barPtr(x,p); // Makes a copy of p
-   delete p; // We allocated p, so we destroy it.
-\end{alltt}
-
-
-\subsubsection{C and Fortran bindings}
-
-C and Fortran programmers can use a limited subset of the
-\kw{PUP::er} capability.  The routines all take a 
-handle named \kw{pup\_er}.  The routines 
-have the prototype:
-\begin{alltt}
-void pup\_\kw{type}(pup\_er p,\kw{type} *val);
-void pup\_\kw{type}s(pup\_er p,\kw{type} *vals,int nVals);
-\end{alltt}
-The first call is for use with a single element;
-the second call is for use with an array.
-The supported types are char, short, int, long,
-uchar, ushort, uint, ulong, float, and double,
-which all have the usual C meanings.
-
-A byte-packing routine
-\begin{alltt}
-void pup\_bytes(pup\_er p,void *data,int nBytes);
-\end{alltt}
-is also provided, but its use is discouraged
-for cross-platform puping.
-
-\kw{pup\_isSizing}, \kw{pup\_isPacking}, \kw{pup\_isUnpacking},
-and \kw{pup\_isDeleting} calls are also available.
-Since C and Fortran have no destructors, you should 
-actually deallocate all data when passed a deleting \kw{pup\_er}.
-
-C and Fortran users cannot use \kw{PUP::able} objects, 
-seeking, or write custom \kw{PUP::er}s. Using the \CC\
-interface is recommended.
-
-
-
-\subsubsection{Common PUP::ers}
-
-The most common \kw{PUP::er}s used are \kw{PUP::sizer},
-\kw{PUP::toMem}, and \kw{PUP::fromMem}.  These are sizing,
-packing, and unpacking \kw{PUP::er}s, respectively.
-
-\kw{PUP::sizer} simply sums up the sizes of the native
-binary representation of the objects it is passed.
-\kw{PUP::toMem} copies the binary representation of the
-objects passed into a preallocated contiguous memory buffer.
-\kw{PUP::fromMem} copies binary data from a contiguous memory
-buffer into the objects passed.  All three support the
-\kw{size} method, which returns the number of bytes used
-by the objects seen so far.
-
-Other common \kw{PUP::er}s are \kw{PUP::toDisk}, 
-\kw{PUP::fromDisk}, and \kw{PUP::xlater}.  The first
-two are simple filesystem variants of the \kw{PUP::toMem} 
-and \kw{PUP::fromMem} classes; \kw{PUP::xlater} translates
-binary data from an unpacking PUP::er into the machine's
-native binary format, based on a \kw{machineInfo} structure
-that describes the format used by the source machine.
-
-
-\subsubsection{PUP::seekBlock}
-
-It may rarely occur that you require items to be unpacked
-in a different order than they are packed.  That is, you
-want a seek capability.  \kw{PUP::er}s support a limited 
-form of seeking.
-
-To begin a seek block, create a \kw{PUP::seekBlock} object
-with your current PUP::er and the number of ``sections'' to 
-create.  Seek to a (0-based) section number
-with the seek method, and end the seeking with the endBlock method.
-For example, if we have two objects A and B, where A's pup
-depends on and affects some object B, we can pup the two with:
-
-\begin{alltt}
-void pupAB(PUP::er &p)
-\{
-  ... other fields ...
-  PUP::seekBlock s(p,2); //2 seek sections
-  if (p.isUnpacking()) 
-  \{//In this case, pup B first
-    s.seek(1);
-    B.pup(p);
-  \}
-  s.seek(0);
-  A.pup(p,B);
-  
-  if (!p.isUnpacking()) 
-  \{//In this case, pup B last
-    s.seek(1);
-    B.pup(p);
-  \}
-  s.endBlock(); //End of seeking block
-  ... other fields ...
-\};
-\end{alltt}
-
-Note that without the seek block, A's fields would be unpacked
-over B's memory, with disasterous consequences.
-The packing or sizing path must traverse the seek sections
-in numerical order; the unpack path may traverse them in any
-order.  There is currently a small fixed limit of 3 on the 
-maximum number of seek sections.
-
-
-\subsubsection{Writing a PUP::er}
-
-System-level programmers may occasionally find it useful to define
-their own \kw{PUP::er} objects.  The system \kw{PUP::er} class is 
-an abstract base class that funnels all incoming pup requests
-to a single subroutine:
-
-\begin{alltt}
-    virtual void bytes(void *p,int n,size\_t itemSize,dataType t);
-\end{alltt}
-
-The parameters are, in order, the field address, the number of items,
-the size of each item, and the type of the items. The \kw{PUP::er}
-is allowed to use these fields in any way.  However, an isSizing
-or isPacking PUP::er may not modify the referenced user data; 
-while an isUnpacking PUP::er may not read the original values of 
-the user data.  If your PUP::er is not clearly packing (saving values
-to some format) or unpacking (restoring values), declare it as 
-sizing \kw{PUP::er}.
-
-
-
index 20fed31acac5334137b902c672931a7913a4a47a..f05c0e518fe3bc9e85df829407448d46c70e2eaa 100644 (file)
@@ -1,74 +1,4 @@
-\subsection{Reductions}
-
-\label{reductions}
-
-A \index{array 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
-over the members of an array or group.
-
-The data to be reduced comes from a call to the member \kw{contribute} 
-method:
-\begin{alltt}
-void contribute(int nBytes, const void *data, CkReduction::reducerType type);
-\end{alltt}
-
-This call contributes \kw{nBytes} bytes starting at \kw{data} to the
-reduction \kw{type} (see reduction types, below).  Unlike sending a
-message, you may use \kw{data} after the call to \kw{contribute}.  All
-members of the chare array or group must call \kw{contribute}, and all of them must use the same
-reduction type.  
-
-When you create a new chare array element, it is expected
-to contribute to the next reduction not already in progress on that
-processor.  The
-reduction will complete properly even if elements are migrated
-or deleted during the reduction. 
-
-For example, if we want to sum each array/group member's single integer myInt, 
-we would use:
-
-\begin{alltt}
-    // Inside any member method
-    int myInt=get_myInt();
-    contribute(sizeof(int),\&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 a chare array has a pair of
-doubles \uw{forces}[2], the corresponding elements of which are to be added across
-all elements, from each element call:
-
-\begin{alltt}
-    double forces[2]=get_my_forces();
-    contribute(2*sizeof(double),forces,CkReduction::sum_double);
-\end{alltt}
-
-This will result in a {\tt double} array of 2 elements, the first of which
-contains the sum of all \uw{forces}[0] values, with the second element 
-holding the sum of all \uw{forces}[1] values of the chare array elements.
-
-Note that since C++ arrays (like \uw{forces}[2]) are already pointers, we 
-don't use \&\uw{forces}.
-
-Reductions do not have to specify commutative-associative operations on data;
-they can also be used to signal the fact that all array/group members
-have reached a certain synchronization point. In this case, a simpler version
-of contribute may be used:
-
-%Sometimes it is not important the data to be reduced, but only the fact that all
-%elements have reached a synchronization point. In this case a simpler version of
-%contribute can be used:
-
-\begin{alltt}
-    contribute();
-\end{alltt}
-
-In all cases, the result of the reduction operation is passed to the {\em reduction
-client}.  Many different kinds of reduction clients can be used, as
-explained below (Section~\ref{reductionClients}).
-
-
+\subsection{Advanced Reductions}
 
 \subsubsection{Reduction Clients}
 
@@ -163,44 +93,6 @@ reduction message. To set the tag on a reduction message, the
 contributors can pass an additional integer argument at the end of the
 {\tt contribute()} call.
 
-\subsubsection{Typed Reductions}
-
-\label{typed_reductions}
-
-Typically the client entry method of a reduction takes a single argument of
-type CkReductionMsg. However, by giving an entry method the
-\kw{reductiontarget} attribute in the {\tt .ci} file, you can instead use entry methods that take
-arguments of the same type as specified by the {\em contribute} call.  
-When creating a callback to the
-reduction target, the entry method index is generated by 
-{\tt CkReductionTarget(ChareClass, method\_name)} 
-instead of {\tt CkIndex\_ChareClass::method\_name(...)}.
-For example,
-the code for a typed reduction that yields an {\tt int}, would look like this:
-
-\begin{alltt}
-  // In the .ci file...
-  entry [reductiontarget] void done(int result);
-
-  // In some .cc file: 
-  // Create a callback that invokes the typed reduction client
-  CkCallback cb(CkReductionTarget(Driver,done), driverProxy);
-
-  // Contribution to the reduction...
-  contribute(sizeof(int), &intData, CkReduction::sum_int, cb);
-
-  // Definition of the reduction client...
-  void Driver::done(int result) 
-  \{
-    CkPrintf("Reduction value: \%d", result);
-  \}
-\end{alltt}
-
-This will also work for arrays of data elements, and for any user-defined type with a PUP method
-(see ~\ref{sec:pup}). If you know that the reduction will yield a particular
-number of elements, say 3 {\tt int}s, you can also specify a reduction target which
-takes 3 {\tt int}s and it will be invoked correctly. 
-
 \subsubsection{Built-in Reduction Types}
 
 \label{builtin_reduction}
@@ -300,7 +192,6 @@ don't want to undertake multiple reductions, it may be best to define
 your own reduction type.  See the next section
 (Section~\ref{new_type_reduction}) for details.
 
-
 \subsubsection{Defining a New Reduction Type}
 
 \label{new_type_reduction}
index bc8f8d997b9dceab8babf954eda8058cce5f833e..ffd25e42b18c32b9849b193debb6094a939e188c 100644 (file)
@@ -1,4 +1,4 @@
-\section{Structured Dagger}
+\subsection{Structured Dagger}
 \label{sec:sdag}
 
 \charmpp\ is based on the Message-Driven parallel programming paradigm.  The
@@ -16,27 +16,27 @@ arises in many situations. Let us consider an example:
 %\begin{figure}[ht]
 \begin{center}
 \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);
-    \}
-\}
+      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}
@@ -85,22 +85,25 @@ Lets us code our previous example using threads.
 %\begin{figure}[ht]
 \begin{center}
 \begin{alltt}
-void compute_thread(int first_index, int second_index)\{
+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)\{
+  \}
+  void recvFirst(void)
+  \{
     recv(first, sizeof(Patch), ANY_PE, FIRST_TAG);
     filter(first);
-\}
-void recvSecond(void)\{
+  \}
+  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}
@@ -126,21 +129,21 @@ adding any significant overhead.
 %\begin{figure}[ht]
 \begin{center}
 \begin{alltt}
-array[1D] compute_object \{
+  array[1D] compute_object \{
     entry void recv_first(Patch *first);
     entry void recv_second(Patch *first);
     entry void 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); \}
+      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}
@@ -167,7 +170,7 @@ interface file. The implementation of the entry methods that contain the
 when-block is written using the \sdag\ language. Grammar of \sdag\ is given in
 the EBNF form below.
 
-\subsection{Usage}
+\subsubsection{Usage}
 
 You can use SDAG to implement entry methods for any chare, chare array, group,
 or nodegroup. Any entry method implemented using SDAG must be implemented in the
@@ -218,19 +221,19 @@ For example, an array named ``Foo'' that uses sdag code might contain:
 
 \begin{alltt}
 class Foo : public CBase_Foo \{
-    public:
+public:
     Foo_SDAG_CODE
     Foo(...) \{
-        __sdag_init();
-        ...
+       __sdag_init();
+       ...
     \}
     Foo(CkMigrateMessage *m) \{
-        __sdag_init();
+       __sdag_init();
     \}
     
     void pup(PUP::er &p) \{
-        CBase_Foo::pup(p);
-        __sdag_pup(p);
+       CBase_Foo::pup(p);
+       __sdag_pup(p);
     \}
 \};
 \end{alltt}
@@ -239,9 +242,9 @@ For more details regarding \sdag{}, look at the example located in the
 {\tt examples/charm++/hello/sdag} directory in the \charmpp\ distribution.
 
 
-\subsection{Grammar}
+\subsubsection{Grammar}
 
-\subsubsection{Tokens}
+\paragraph{Tokens}
 
 \begin{alltt}
   <ident> = Valid \CC{} identifier 
@@ -249,7 +252,7 @@ For more details regarding \sdag{}, look at the example located in the
   <\CC{}-code> = Valid \CC{} code 
 \end{alltt}
 
-\subsubsection{Grammar in EBNF Form}
+\paragraph{Grammar in EBNF Form}
 
 \begin{alltt}
 <sdag> := <class-decl> <sdagentry>+ 
index 28a85a32778dde047ba53853205132cbff9f5b08..edec19142dc15d118ebf391a1417c0ed1e149903 100644 (file)
@@ -193,10 +193,3 @@ The differences in Poll Mode may be apparent. There is no callback function whic
 The server should call Deposit with the same global size and combiner type on all of the array elements which correspond to the ``this'' parameter.
 
 The latest version of liveVizPoll is not backwards compatable with older versions. The old version had some fundamental problems which would occur if a server generated an image before a client requested it. Thus the new version buffers server generated images until requested by a client. Furthermore the client requests are also buffered if they arrive before the server generates the images. Problems could also occur during migration with the old version.
-
-\section{Caveats}
-There is a known bug caused by how ``liveVizDeposit'' internally uses a reduction to build the image.
-
-Currently its contribute call is handled as if it were the chare calling ``liveVizDeposit'' that actually contributed to the liveViz reduction.
-If there is any other reduction going on elsewhere in this chare, some liveViz contribute calls might be issued before the corresponding non-liveViz contribute is reached.
-This would imply that image data would be treated as if were part of the non-liveViz reduction, leading to unexpected behavior potentially anywhere in the non-liveViz code.
index bbfb431c9ada13c06e46248962908b17be38d2d2..5c4ae3e9bb000125e442c986d105f4ea470734b6 100644 (file)
@@ -229,7 +229,7 @@ FAX: (217) 333-3501
    \textsf{\Huge \@title \\}
  \end{flushright}
  \vspace{\fill}
- \@credits \\
%\@credits \\
  \rule{\textwidth}{3pt}
  \begin{flushright}
    {\large Version \@version}
index 582a43767143dae6cb8ccdd1c8fb5848bcbc426d..d35779b348f46842a822771975c6280eb3ee7cb5 100644 (file)
@@ -471,11 +471,10 @@ contact the developers if you have input or suggestions.
 \label{sec::visualization}
 
 The \projections{} Java-based visualization tool (henceforth refered
-to as simply \projections{}) does not come pre-built with the \charmpp{}
-source release. An anynonymous git archive can be cloned from \\ {\tt
-git://charm.cs.uiuc.edu/projections.git}, this manual will assume the 
-existance of a local copy, the location of which will henceforth be 
-refered to as {\tt PROJECTIONS\_LOCATION}.
+to as simply \projections{}) comes pre-built with the \charmpp{}
+source release. It can be located at \\ {\tt
+CHARM\_LOCATION/tools/projections} which will henceforth be refered to
+as {\tt PROJECTIONS\_LOCATION}.
 
 \subsection{Building \projections{}}