General cleaning, updated for:
authorOrion Lawlor <olawlor@acm.org>
Fri, 6 Jul 2001 18:14:28 +0000 (18:14 +0000)
committerOrion Lawlor <olawlor@acm.org>
Fri, 6 Jul 2001 18:14:28 +0000 (18:14 +0000)
-Parameter marshalling throughout
-New CkIndex_ entry point index syntax
-CkLocal call for Chares and Arrays
-New groupProxy[pe] syntax

16 files changed:
doc/charm++/arrays.tex
doc/charm++/chares.tex
doc/charm++/groups.tex
doc/charm++/inhertmplt.tex
doc/charm++/intro.tex
doc/charm++/io.tex
doc/charm++/manual.tex
doc/charm++/marshalling.tex
doc/charm++/messages.tex
doc/charm++/modules.tex
doc/charm++/nodegroups.tex
doc/charm++/othercalls.tex
doc/charm++/overview.tex
doc/charm++/pup.tex
doc/charm++/quiesce.tex
doc/charm++/seqobjs.tex [deleted file]

index fae0fb3370c0a49b219e3256ed7e16c7aa04286e..1b3bd9b866b18646904383aa05aa09cf3aa4b0ba 100644 (file)
@@ -1,7 +1,7 @@
 \subsection{Chare Arrays}
 
 Chare arrays \index{arrays} are arbitrarily-sized collections of chares.  The
-entire array is has a globally unique identifier of type \kw{CkArrayID}, and
+entire array has a globally unique identifier of type \kw{CkArrayID}, and
 each element has a unique index of type \kw{CkArrayIndex}.  A \kw{CkArrayIndex}
 can be a single integer (i.e. 1D array), several integers (i.e. a
 multidimentional array), or an arbitrary string of bytes (e.g. a binary tree
@@ -21,13 +21,8 @@ as:
 \begin{alltt}
 //In the .ci file:
 array [1D] A \{
-  entry A();
-  entry void someEntry(M1 *);
-\};
-
-//In the .h file:
-class M1:public CMessage_M1 \{
-//...message fields...
+  entry A(\uw{parameters1});
+  entry void someEntry(\uw{parameters2});
 \};
 \end{alltt}
 
@@ -41,10 +36,10 @@ and ``thisIndex'', the element's array index.
 \begin{alltt}
 class A : public ArrayElement1D \{
   public:
-    A(void);
+    A(\uw{parameters1});
     A(CkMigrateMessage *);
 
-    void someEntry(M1 *);
+    void someEntry(\uw{parameters2});
 \};
 \end{alltt}
 
@@ -71,10 +66,10 @@ index arrays.  These arrays can be declared as:
 \begin{alltt}
 //In the .ci file:
 message MyMsg;
-array [1D] A1 \{ entry A1(); entry void e(MyMsg *m);\}
-array [2D] A2 \{ entry A2(); entry void e(MyMsg *m);\}
-array [3D] A3 \{ entry A3(); entry void e(MyMsg *m);\}
-array [Foo] AF \{ entry AF(); entry void e(MyMsg *m);\}
+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 [Foo] AF \{ entry AF(); entry void e(\uw{parameters});\}
 \end{alltt}
 
 The last declaration expects an array index of type \kw{CkArrayIndex}\uw{Foo},
@@ -83,11 +78,6 @@ which must be defined before including the \texttt{.decl.h} file
 
 \begin{alltt}
 //In the .h file:
-class MyMsg: public CMessage_MyMsg \{
-public: 
-  int val;
-  MyMsg(int i) \{val=i;\}
-\}
 class A1:public ArrayElement1D \{ public: A1()\{\} ...\};
 class A2:public ArrayElement2D \{ public: A2()\{\} ...\};
 class A3:public ArrayElement3D \{ public: A3()\{\} ...\};
@@ -112,7 +102,7 @@ use (x,y,z); and for user-defined types use [f] or (f).
 
 You insert elements into the array by indexing the proxy
 and calling insert.  The insert call optionally takes 
-a message, which is passed to the constructor, or a
+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 
@@ -126,25 +116,25 @@ After creating elements, start using the array with
 int x,y,z;
 CProxy_A1 a1=CProxy_A1::ckNew();  //Creates new 1D array
 for (x=...) \{
-   a1[x  ].insert();  //Bracket syntax
-   a1(x+1).insert();  // or equivalent parenthesis syntax
+   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 new 2D array
 for (x=...) for (y=...)
-   a2(x,y).insert();  //Can't use brackets!
+   a2(x,y).insert(\uw{parameters});  //Can't use brackets!
 a2.doneInserting();
 
 CProxy_A3 a3=CProxy_A3::ckNew();   //Creates new 3D array
 for (x=...) for (y=...) for (z=...)
-   a3(x,y,z).insert();
+   a3(x,y,z).insert(\uw{parameters});
 a3.doneInserting();
 
 CProxy_AF aF=CProxy_AF::ckNew();   //Creates new user-defined index array
 for (...) \{
-   aF[CkArrayIndexFoo(...)].insert(); //Use brackets...
-   aF(CkArrayIndexFoo(...)).insert(); //  ...or parenthesis
+   aF[CkArrayIndexFoo(...)].insert(\uw{parameters}); //Use brackets...
+   aF(CkArrayIndexFoo(...)).insert(\uw{parameters}); //  ...or parenthesis
 \}
 aF.doneInserting();
 
@@ -161,7 +151,7 @@ This is exactly equivalent to the loop:
 \begin{alltt}
 CProxy_A1 a = CProxy_A1::ckNew();
 for (i=0;i<num_elements;i++)
-       a1[i].insert();
+       a1[i].insert(\uw{parameters});
 a1.doneInserting();
 \end{alltt}
 
@@ -192,15 +182,16 @@ 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{Messages and Broadcasts}
+
+\subsubsection{Messages}
 
 To send a \index{Array message} message to an array element, index the proxy 
-and call the method name, possibly passing a message:
+and call the method name:
 
 \begin{alltt}
-a1[i].doSomething(new MyMsg(7));
-a3(x,y,z).doAnother(new MyMsg(23));
-aF[CkArrayIndexFoo(...)].doAgain();
+a1[i].doSomething(\uw{parameters});
+a3(x,y,z).doAnother(\uw{parameters});
+aF[CkArrayIndexFoo(...)].doAgain(\uw{parameters});
 \end{alltt}
 
 You may invoke methods on array elements that have not yet
@@ -224,11 +215,13 @@ Messages sent to migrating elements will be delivered after
 the migrating element arrives.  It is an error to send 
 a message to a deleted array element.
 
+
+\subsubsection{Broadcasts}
 To \index{Array broadcast} broadcast a message to all the current elements of an array, 
 simply omit the index, as:
 
 \begin{alltt}
-a3.doIt(new MyMsg(7)); //<- invokes doIt(7) on each array element
+a3.doIt(\uw{parameters}); //<- invokes doIt on each array element
 \end{alltt}
 
 The broadcast message will be delivered to every existing array 
@@ -236,6 +229,26 @@ element exactly once.  Broadcasts work properly even with ongoing
 migrations, insertions, and deletions.
 
 
+\subsubsection{Local Access}
+\experimental{}
+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 call \kw{ckLocal} anew each time the element may have
+migrated; e.g., at the start of each entry method.
+
+
+
 \subsubsection{Reductions on Chare Arrays}
 A \index{Array reduction}reduction applies a single operation (e.g. add,
 max, min, ...) to data items scattered across many processors and
@@ -407,8 +420,8 @@ public:
         nInts=sizeof(f)/sizeof(int);
     \}
     //Not required, but convenient: cast-to-foo operators
-    operator foo &() {return f;}
-    operator const foo &() const {return f;}
+    operator foo &() \{return f;\}
+    operator const foo &() const \{return f;\}
 \};
 \end{alltt}
 
@@ -416,13 +429,13 @@ 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
+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. Larger values will increase the
-size of each message.
+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
 
index 8278ecc9e976c9ca3750cbda2f1683d4997ac304..8fdd75529f4e75b3938b4a178e1465cf14f11a0f 100644 (file)
@@ -7,8 +7,8 @@ must be specified in the interface (\texttt{.ci}) file:
 \begin{alltt}
 chare ChareType
 \{
-    entry   ChareType             (MessageType1 *);
-    entry   void EntryMethodName2 (MessageType2 *);
+    entry   ChareType             (\uw{parameters1});
+    entry   void EntryMethodName2 (\uw{parameters2});
 \};
 \end{alltt}
 
@@ -20,9 +20,9 @@ have the form:
         // Data and member functions as in C++ 
         // One or more entry methods definitions of the form: 
    public: 
-      ChareType(MessageType1 *MsgPointer
+      ChareType(\uw{parameters2}
          \{ // C++ code block  \} 
-      void EntryMethodName2(MessageType2 *MsgPointer
+      void EntryMethodName2(\uw{parameters2}
          \{ // C++ code block  \} 
    \};
 \end{alltt}
@@ -74,8 +74,8 @@ In the \texttt{mod.ci} file we have:
 \begin{alltt}
 module mod \{
   chare C \{
-    entry C(M1 *);
-    entry void someEntry(M2 *);
+    entry C(\uw{parameters});
+    entry void someEntry(\uw{parameters});
   \};
 \}
 \end{alltt}
@@ -86,8 +86,8 @@ and in the \texttt{mod.h} file:
 #include "mod.decl.h"
 class C : public Chare \{
   public:
-    C(M1 *);
-    void someEntry(M2 *);
+    C(\uw{parameters});
+    void someEntry(\uw{parameters});
 \};
 \end{alltt}
 
@@ -98,21 +98,18 @@ type \kw{CProxy}\_\uw{C}. A number of \index{chare}chare creation calls exist
 as static or instance methods of class \kw{CProxy}\_\uw{chareType}:
 
 \begin{alltt}
-   CProxy_chareType::ckNew(MessageType *msgPtr, CkChareID *vHdl, int destPE);
+   CProxy_chareType::ckNew(\uw{parameters}, CkChareID *vHdl, int destPE);
 \end{alltt}
 
-where each parameter above is optional and where
+Each item above is optional, and:
 
 \begin{itemize}
 
 \item \uw{chareType} is the name of the type of \index{chare}chare to be
 created.
 
-\item \uw{msgPtr} is a pointer to a \index{message}message whose type must
-correspond to the parameter for the \index{constructor}constructor entry method
-\uw{chareType}(\uw{MessageType}*) in \index{chare}chare \uw{chareType}.  This
-parameter may be omitted if the \index{constructor}constructor takes a void
-parameter.
+\item \uw{parameters} must correspond to the parameters for the \index{constructor}constructor entry method.  If the constructor takes void, 
+pass nothing here.
 
 \item \uw{vHdl} is a pointer to a \index{chare}chare handle of type
 \kw{CkChareID}, which is filled by the \kw{ckNew} method. This optional
@@ -156,67 +153,63 @@ method to create chares.
 processor:}
 
 \begin{alltt}
-   MessageType *MsgPtr = new MessageType;
-   CProxy_C *pC = new CProxy_C(MsgPtr);
-      // or
-   MessageType *MsgPtr = new MessageType;
-   CProxy_C::ckNew(MsgPtr);
+   CProxy_C chareProxy = CProxy_C::ckNew(\uw{parameters});
 \end{alltt} 
 
 \item{This will create a new \index{chare}chare of type \uw{C} on processor
 \kw{destPE}:}
 
 \begin{alltt}
-   MessageType *MsgPtr = new MessageType;
-   CProxy_C::ckNew(MsgPtr, destPE);
+   CProxy_C chareProxy = CProxy_C::ckNew(\uw{parameters}, destPE);
 \end{alltt}
 
 \item{The following first creates a \kw{CkChareID} \uw{cid},
 then creates a new \index{chare}chare of type \uw{C} on processor \uw{destPE}:}
 
 \begin{alltt}
-   MessageType *MsgPtr = new MessageType;
    CkChareID cid;
-   CProxy_C::ckNew(MsgPtr, \&cid, destPE);
-   CProxy_C c(cid);
+   CProxy_C::ckNew(\uw{parameters}, \&cid, destPE);
+   CProxy_C chareProxy(cid);
 \end{alltt}
 
 \end{enumerate}
 
 \subsubsection{Method Invocation on Chares}
 
-Before sending a \index{message}message to a \index{chare}chare via an
-\index{entry method}entry method, we need to get a \index{proxy}{\it proxy} of
-that \index{chare}chare using either the chare identifier, or by creating the
-proxy directly from the \index{chare}chare creation (see Section~\ref{chare
-creation}. The following code creates a proxy from a \kw{CkChareID}.
+A message \index{message} may be sent to a \index{chare}chare using the
+notation:
 
-\begin{alltt}
-   CProxy_chareType chareProxy(chareID);
-\end{alltt}
+\begin{tabbing}
+chareProxy.EntryMethod(\uw{parameters})
+\end{tabbing}
+
+This invokes the entry method \uw{EntryMethod} on the chare referred
+to by the proxy \uw{chareProxy}. This call
+is asynchronous and non-blocking; it returns immediately after sending the
+message. 
 
-This declares a proxy named \uw{chareProxy} of \uw{chareType} 
-using \uw{chareID}.  Alternatively, we can create a proxy pointer:
+
+\subsubsection{Local Access}
+\experimental{}
+You can get direct access to a local chare using the
+proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
+to the chare if it exists on the local processor; and NULL if
+the chare does not exist or is on another processor.
 
 \begin{alltt}
-CProxy_chareType *chareProxyPointer = new CProxy_chareType(chareID);
+C *c=chareProxy.ckLocal();
+if (c==NULL) //...is remote-- send message
+else //...is local-- directly use members and methods of c
 \end{alltt}
 
-This creates a pointer named \uw{chareProxyPointer} which points to the proxy. 
 
-A message \index{message} may be sent to a \index{chare}chare using the
-notation:
 
-\begin{tabbing}
-chareProxy.EntryMethod(MessagePointer)
-or,
-chareProxyPointer->EntryMethod(MessagePointer)
-\end{tabbing}
 
-This sends the message pointed to by \uw{MessagePointer} to the
-\index{chare}chare whose proxy/proxy pointer is 
-\uw{chareProxy}/\uw{chareProxyPointer} at the \index{entry method}entry method 
-\uw{EntryMethod},
-which must be a valid entry method of that \index{chare}chare type. This call
-is asynchronous and non-blocking; it returns immediately after sending the
-message. 
+
+
+
+
+
+
+
+
index 9164e7e4efe0e2bd444d887b35258bc94e46ec6f..6cc638733d062e953cf91d069f2c381bfccfab84 100644 (file)
@@ -44,8 +44,8 @@ Given a \texttt{.ci} file as follows:
 
 \begin{alltt}
 group G \{
-  entry G(M1 *);
-  entry void someEntry(M2 *);
+  entry G(\uw{parameters1});
+  entry void someEntry(\uw{parameters2});
 \};
 \end{alltt}
 
@@ -54,101 +54,65 @@ and the following \texttt{.h} file:
 \begin{alltt}
 class G : public Group \{
   public:
-    G(M1 *);
-    void someEntry(M2 *);
+    G(\uw{parameters1});
+    void someEntry(\uw{parameters2});
 \};
 \end{alltt}
 
 we can create a \index{group}group in a manner similar to a regular
-\index{chare}chare.  Note the difference in how the \index{virtual
-handle}virtual handle is created.
+\index{chare}chare. 
 
 \begin{alltt}
-M1 *m1 = new M1;
-CProxy_G *pG = new CProxy_G(m1);
-  // or
-CkGroupID gid = CProxy_G::ckNew(m1);
-CProxy_G g(gid);
+CProxy_G groupProxy = CProxy_G::ckNew(\uw{parameters1});
 \end{alltt}
 
 \subsubsection{Method Invocation on Groups}
 
 Before sending a message to a \index{group}group via an entry
-method, we need to get a proxy of that group using the group identifier (a
-\kw{CkGroupID}). The syntax for obtaining the proxy or a proxy
-pointer is:
-
-\begin{alltt}
- CProxy_groupType groupProxy(groupID);
-  or,
- CProxy_groupType *groupProxyPointer = new CProxy_groupType(groupID);
-\end{alltt}
-
-The first approach creates a proxy to the group represented by \uw{groupID}
-while the second creates a pointer named \uw{groupProxyPointer} to a proxy to
-the group represented by \uw{groupID}. 
+method, we need to get a proxy of that group.
 
 A message may be sent to a particular \index{branch}branch of group using the
 notation:
 
 \begin{alltt}
- groupProxy.EntryMethod(MessagePointer, Processor)
-  or,
- groupProxyPointer->EntryMethod(MessagePointer, Processor)
+ groupProxy[Processor].EntryMethod(\uw{parameters});
 \end{alltt}
 
-This sends the message in \uw{MessagePointer} to the \index{branch}branch of
-the group represented by \uw{groupID} which is on processor number
+This sends the given parameters to the \index{branch}branch of
+the group referred to by \uw{groupProxy} which is on processor number
 \uw{Processor} at the entry method \uw{EntryMethod}, which must be a valid
 entry method of that group type. This call is asynchronous and non-blocking; it
 returns immediately after sending the message.
 
-A message may be broadcast \index{broadcast} to all branches of a branched
-chare (i.e., to all processors) using the notation :
+A message may be broadcast \index{broadcast} to all branches of a group
+(i.e., to all processors) using the notation :
 
 \begin{alltt}
- groupProxy.EntryMethod(MessagePointer)
- groupProxyPointer->EntryMethod(MessagePointer)
+ groupProxy.EntryMethod(\uw{parameters});
 \end{alltt}
 
-This sends the message in \uw{MessagePointer} to all branches of the group at
+This sends the given parameters to all branches of the group at
 the entry method \uw{EntryMethod}, which must be a valid entry method of that
 group type. This call is asynchronous and non-blocking; it returns immediately
 after sending the message.
 
-Note that the programmer relinquishes control of a message after sending it.
-Further access to the message field can cause runtime errors.
 
-
-Sequential objects, chares and other groups can access public members of the
-\index{branch}branch of a group \index{group} {\it on their processor} using
-the following notation:
+Sequential objects, chares and other groups can gain access to the local
+(i.e., on their processor) group object using:
 
 \begin{alltt}
-((GroupType*)CkLocalBranch(CkGroupID groupID))->DataMember
-{\em and} 
-(GroupType*)CkLocalBranch(CkGroupID groupID))->method() 
+GroupType *g=groupProxy.ckLocalBranch();
 \end{alltt}
 
+This call returns a regular \CC\ pointer to the actual object (not a proxy)
+referred to by the proxy \uw{groupProxy}.  Once a proxy to the
+local branch of a group is obtained, that branch can be accessed as a regular
+\CC\ object.  Its public methods can return values, and its public data is 
+readily accessible.
+
 Thus a dynamically created \index{chare}chare can call a public method of a
 group without needing to know which processor it actually resides: the method
-executes in the local \index{branch}branch of the group.  Once a proxy to the
-local branch of a group is obtained, that branch can be thought of as a regular
-object.  Its public methods can return values, and its public data is readily
-accessible.   
-
-\kw{CkLocalBranch} returns a generic (\texttt{void *}) pointer.  It needs to be
-cast to a pointer of appropriate classe before invoking methods or accessing
-data members. \charmpp\ provides another way to do this using the generated
-\index{proxy}{\em proxy} classes. One may call the static method
-\kw{ckLocalBranch} of the proxy class of appropriate group to get the correct
-type of pointer.  For example, method \uw{foo} can to be invoked on the local
-\index{branch}branch of a group \uw{G} with \uw{gid} as CkGroupID as:
-
-\begin{alltt}
-(CProxy_G::ckLocalBranch(gid))->foo(...);
-\end{alltt}
-\index{ckLocalBranch}
+executes in the local \index{branch}branch of the group.
 
 One very nice use of Groups is to reduce the number of messages sent between
 processors by collecting the data from all the chares on a single processor
@@ -157,5 +121,11 @@ break up the work of a problem.  Also, create a group.  When a particular chare
 finishes its work, it reports its findings to the local branch of the group.
 When all the chares on one processor are complete, the local branch of the
 group can then report to the main chare.  This reduces the number of messages
-sent to main from the number of chares created to the number of processors.     
+sent to main from the number of chares created to the number of processors. 
+
+
+
+
+
+
 
index e96bf3d327c23241026bf3b719c93d033142ac79..75fad0ffbb3ea5cdde998fe29913e4acb0bf6d50 100644 (file)
@@ -18,13 +18,13 @@ declared in the \charmpp\ interface file to be explicitly derived from
 
 \begin{alltt}
   chare BaseChare \{
-    BaseChare(someMessage *);
-    baseMethod(void);
+    entry BaseChare(someMessage *);
+    entry void baseMethod(void);
     ...
   \}
   chare DerivedChare : BaseChare \{
-    DerivedChare(otherMessage *);
-    derivedMethod(void);
+    entry DerivedChare(otherMessage *);
+    entry void derivedMethod(void);
     ...
   \}
 \end{alltt}
@@ -43,13 +43,13 @@ The class definitions of both these chares should look like:
     // private or protected data
     public:
       BaseChare(someMessage *);
-      baseMethod(void);
+      void baseMethod(void);
   \};
   class DerivedChare : public BaseChare \{
     // private or protected data
     public:
       DerivedChare(otherMessage *);
-      derivedMethod(void);
+      void derivedMethod(void);
   \};
 \end{alltt}
 
@@ -66,40 +66,64 @@ as shown below:
   ...
   Cproxy_BaseChare *pb = pd;
   pb->baseMethod();    // OK
-  pb->derivedMethod(); // ERROR
+  pb->derivedMethod(); // COMPILE ERROR
 \end{alltt}
 
 Note that \CC\ calls the default constructor \index{default constructor} of the
 base class from any constructor for the derived class where base class
 constructor is not called explicitly. Therefore, one should always provide a
-default constructor for the base class to avoid explicitly calling another base
+default constructor for the base class, or explicitly call another base
 class constructor.
 
 Multiple inheritance \index{multiple inheritance} is also allowed for Chares
-and Groups. However, one should make sure that each of the base classes inherit
+and Groups. Often, one should make each of the base classes inherit
 ``virtually'' from \kw{Chare} or \kw{Group}, so that a single copy of
 \kw{Chare} or \kw{Group} exists for each multiply derived class.
 
-One may have {\em virtual} entry methods \index{virtual} in base chare classes.
-They are specified by the entry attribute \kw{virtual} in the interface file.
-Also, such a method could be pure virtual \index{pure virtual} (where
-implementation of this method is not given.) It is noted with the usual \CC\
-syntax of ``{\tt =0}'' even in the interface file. Base classes with pure
-virtual methods are called {\em abstract} base classes \index{abstract base
-class} in OO-lingo. Note that, though instances of abstract base chares cannot
-be created, a proxy objects of such a type can be created by constructing it
-with the chareID of the concrete derived chare. Invoking methods on this proxy
-object would invoke those methods remotely on the concrete derived class
-instance.
+Entry methods are inherited in the
+same manner as methods of sequential \CC{} objects.  
+To make an entry method virtual, just add the keyword \kw{virtual}
+to the corresponding chare method-- no change is needed in the interface file.
+Pure virtual entry methods also require no special description
+in the interface file.
+
 
 \subsection{Inheritance for Messages}
 \index{message inheritance}
 
-Similar to Chares, messages can also be derived from base messages. One needs
-to specify this in the \charmpp\ interface file similar to the Chare
-inheritance specification (that is, without the \kw{public} access specifier.)
-Message inheritance makes it possible to send a message of derived type to the
-method expecting a base class message.
+Messages cannot inherit from other messages.  A message can, however,
+inherit from a regular \CC\ class.  For example:
+
+\begin{alltt}
+//In the .ci file:
+  message BaseMessage1;
+  message BaseMessage2;
+
+//In the .h file:
+  class Base \{
+    // ...
+  \};
+  class BaseMessage1 : public Base, public CMessage_BaseMessage1 \{
+    // ...
+  \};
+  class BaseMessage2 : public Base, public CMessage_BaseMessage2 \{
+    // ...
+  \};
+\end{alltt}
+
+Messages cannot contain virtual methods
+or virtual base classes unless you use a packed message.
+Parameter marshalling has complete support for inheritance, virtual
+methods, and virtual base classes via the PUP::able framework.
+
+
+% ( I think the following is now a lie  OSL 7/5/2001 )  
+%Similar to Chares, messages can also be derived from base messages. One needs
+%to specify this in the \charmpp\ interface file similar to the Chare
+%inheritance specification (that is, without the \kw{public} access specifier.)
+%Message inheritance makes it possible to send a message of derived type to the
+%method expecting a base class message.
+
 
 \subsection{Generic Programming Using Templates}
 \index{templates}
index 6563a230724abf08cfd357229fb0be5075d314dc..c3c7ca845fbb0dbc5884d97e49c3da8a4e51bd42 100644 (file)
@@ -66,8 +66,6 @@ The programmer-visible entities in a \charmpp\ program are:
       English for chore.
       }
 \item Communication Objects : Messages
-\item Chare Groups and Nodegroups
-\item Chare Arrays
 \item Readonly data
 \end{itemize}
 
index 362bd731f9d367c5a213edfd8bee24b91262c6d1..52fb5e4f9b8b7565c96a21d7aa1dd30dd3f7eb77 100644 (file)
@@ -38,7 +38,7 @@ only after all input has been retrieved.
 
 For \CC\ style stream-based I/O, \charmpp\ offers \kw{ckin},
 \kw{ckout}, and \kw{ckerr} in the place of cin, cout, and cerr.  The
-\CC streams and their \charmpp\ equivalents are related in the same
+\CC\ streams and their \charmpp\ equivalents are related in the same
 manner as printf and scanf are to \kw{CkPrintf} and \kw{CkScanf}.  The
 \charmpp\ streams are all used through the same interface as the \CC\ 
 streams, and all behave in a slightly different way, just like C-style
index 349b4bf5e2c3128e79e335659bd2203102d0e74c..4a209fe9784eee1db4eea6d55b530a12904b875c 100644 (file)
@@ -60,9 +60,9 @@ for the changes to the system since the last release.
 
 \section{The \charmpp\ Language}
   \input{modules}      
+  \input{entry}
   \input{marshalling}  
   \input{messages}
-  \input{seqobjs}
   \input{chares}
   \input{groups}
   \input{nodegroups}
index fec0e753b46c534dd9d2f0c2fd1d65edbd6fcf42..14a11676f8ffa45da901bdf3960d7f173f021a7c 100644 (file)
@@ -1,5 +1,7 @@
 \subsection{Parameter Marshalling}
-       
+\label{marshalling}
+
+\experimental{}        
 In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
 nodegroups communicate by invoking each others methods. 
 The methods may either take several parameters, described here; 
@@ -24,8 +26,8 @@ we must specify the length of the array in the interface file, as:
   entry void bar(int n,double arr[n]);
 \end{alltt}
 Since \CC\ does not recognize this syntax, the array data
-should be passed to the chare proxy as a simple pointer.
-The array data will be copied sent to the
+must be passed to the chare proxy as a simple pointer.
+The array data will be copied and sent to the
 destination processor, where the chare will receive the copy
 via a simple pointer again.  The remote copy of the data
 will be kept until the remote method returns, when
@@ -37,8 +39,8 @@ uses call-by-value, even for arrays and structures.
 
 This also means the data must be copied on the sending 
 side, and to be kept must be copied again 
-at the receive side-- for a more efficient approach,
-use the message objects described in the next section.
+at the receive side.  Especially for large arrays, this 
+is less efficient than messages, as described in the next section.
 
 Array parameters and other parameters can be combined in arbitrary ways, as:
 \begin{alltt}
@@ -51,6 +53,9 @@ The array length expression between the square brackets can be
 any valid C++ expression, and may depend in any way on any of the passed
 parameters, global variables, or global data.  The array length expression
 is evaluated exactly once per invocation, on the sending side only.
+Thus executing the \kw{doGeneral} method above will invoke the 
+(user-defined) \kw{product} function exactly once on the sending
+processor.
 
 \subsubsection{Marshalling User-Defined Structures and Classes}
 
@@ -62,22 +67,22 @@ with no further effort:
 
 \begin{alltt}
 //Declarations:
-class point3d {
+class point3d \{
 public:
     double x,y,z;    
-};
+\};
 
-typedef struct {
+typedef struct \{
     int refCount;
     char data[17];
-} refChars;
+\} refChars;
 
-class date {
+class date \{
 public:
     char month,day;
     int year;
     //...non-virtual manipulation routines...
-};
+\};
 
 //In the .ci file:
     entry void pointRefOnDate(point3d &p,refChars r[d.year],date &d);
@@ -93,9 +98,9 @@ allocated data or virtual methods can only be passed as
 parameters, but never in arrays.  They also must include a pup
 routine and \CC\ operator| (see the PUP chapter for details).
 \kw{PUP::able} structures may be passed via a pointer,
-but will be dynamically allocated on the receive side
-but, for historical reasons, cannot appear alone in the
-parameter list (or else they are confused with messages).
+but will be copied and then dynamically allocated on the receive side.
+For historical reasons, pointer-accessible structures cannot appear 
+alone in the parameter list (because they are confused with messages).
 
-Complicated structures are usually most efficiently passed 
+Large, complicated structures are most efficiently passed 
 via messages; not marshalling.
index 81acdf731e29f0d6b520f15857573f4e2881fef2..608d1d21cc0bab7a543df35ff287841ff6df43ff 100644 (file)
@@ -1,7 +1,17 @@
 \subsection{Messages}
-
-In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
-nodegroups communicate using remote method invocation.  The methods may either take marshalled parameters, described in the previous section; or messages. Messages are lower level, more efficient, more flexible, and much more difficult to use than parameter marshalling.
+\label{messages}
+A message encapsulates all the parameters sent to an
+entry method.  Since the parameters are already encapsulated,
+sending messages is often more efficient than parameter marshalling.
+In addition, messages are easier to queue and store on the
+receive side.
+
+The largest difference between parameter marshalling and messages
+is that entry methods {\em keep} the messages passed to them.
+Thus each entry method must be passed a {\em new} message.
+On the receiving side, the entry method must either store the
+passed message or explicitly {\em delete} it, or else the message
+will never be destroyed, wasting memory.
 
 Several kinds of message are available.
 Regular \charmpp{} messages are objects of
@@ -9,16 +19,12 @@ Regular \charmpp{} messages are objects of
 length arrays (arrays with sizes specified at runtime) and still have these
 pointers to be valid when messages are sent across processors, with some
 additional coding.  Also available is a mechanism for assigning
-\textit{priorities} to messages that applies all kinds of messages, a detailed
-discussion of priorities appears later in this section.
+\textit{priorities} to messages that applies all kinds of messages.
+A detailed discussion of priorities appears later in this section.
 
 Like all other entities involved in asynchronous method invocation, messages
-need to be declared in the {\tt .ci} file.
-
-Message definitions that may appear in the {\tt .h} or {\tt .C} file are very
-similar to class definitions in \CC.
-
-In the {\tt .ci} file (the interface file), a message is declared as: 
+need to be declared in the {\tt .ci} file. In the {\tt .ci} file (the
+interface file), a message is declared as: 
 
 \begin{alltt}
  message MessageType;
@@ -120,151 +126,6 @@ be deleted using the standard \CC{} \kw{delete} operator.
 There are no limitations of the methods of message classes except that the
 message class may not redefine operators \texttt{new} or \texttt{delete}.
 
-\subsubsection{Message Packing}
-\label{message packing}
-\index{message packing}
-\index{packed messages}
-
-When one declares \charmpp\ messages in the \texttt{.ci} file, the translator
-generates code to register those messages along with their size with the
-runtime system. This information is later used to efficiently allocate messages
-by the runtime system.
-
-In many cases, the messages store {\em non-linear} data structures using
-pointers.  Examples of these are binary trees, hash tables etc. Thus, the
-message itself contains only a pointer to the actual data. When the message is
-sent to the same processor, these pointers point to the original locations,
-which are within the address space of the same processor, however, when such a
-message is sent to other processors, these pointers will point to invalid
-locations.
-
-Thus, the programmer needs a way to ``serialize'' these messages
-\index{serialized messages}\index{message serialization}{\em only if} the
-message crosses the address-space boundary.  \charmpp{} provides a way to do
-this serialization by allowing the developer to override the default
-serialization methods generated by the \charmpp{} interface translator.
-Note that this low-level serialization has nothing to do with the PUP framework described later.
-
-Packed messages are declared in the {\tt .ci} file the same way as ordinary
-messages:
-
-\begin{alltt}
-message PMessage;
-\end{alltt}
-
-Like all messages, the class \uw{PMessage} needs to inherit from
-\uw{CMessage\_PMessage} and should provide two {\em static} methods: \kw{pack}
-and \kw{unpack}. These methods are called by the \charmpp\ runtime system, when
-the message is determined to be crossing address-space boundary. The prototypes
-for these methods are as follows:
-
-\begin{alltt}
-static void *PMessage::pack(PMessage *in);
-static PMessage *PMessage::unpack(void *in);
-\end{alltt}
-
-Typically, the following tasks are done in \kw{pack} method:
-
-\begin{itemize}
-
-\item Determine size of the buffer needed to serialize message data.
-
-\item Allocate buffer using the \kw{CkAllocBuffer} function. This function
-takes in two parameters: input message, and size of the buffer needed, and
-returns the buffer.
-
-\item Serialize message data into buffer (alongwith any control information
-needed to de-serialize it on the receiving side.
-
-\item Free resources occupied by message (including message itself.)  
-
-\end{itemize}
-
-On the receiving processor, the \kw{unpack} method is called. Typically, the
-following tasks are done in the \kw{unpack} method:
-
-\begin{itemize}
-
-\item Allocate message using \kw{CkAllocBuffer} function. {\em Do not
-use \kw{new} to allocate message here. If the message constructor has
-to be called, it can be done using the in-place \kw{new} operator.}
-
-\item De-serialize message data from input buffer into the allocated message.
-
-\item Free the input buffer using \kw{CkFreeMsg}.
-
-\end{itemize}
-
-Here is an example of a packed-message implementation:
-
-\begin{alltt}
-// File: pgm.ci
-mainmodule PackExample \{
-  ...
-  message PackedMessage;
-  ...
-\};
-
-// File: pgm.h
-...
-class PackedMessage : public CMessage_PackedMessage
-\{
-  public:
-    BinaryTree<char> btree; // Non-linear data structure used in e.g. only 
-    static void* pack(PackedMessage*);
-    static PackedMessage* unpack(void*);
-    ...
-\};
-...
-
-// File: pgm.C
-...
-void*
-PackedMessage::pack(PackedMessage* inmsg)
-\{
-  int treesize = inmsg->btree.getFlattenedSize();
-  int totalsize = treesize + sizeof(int);
-  char *buf = (char*)CkAllocBuffer(inmsg, totalsize);
-  // buf is now just raw memory to store the data structure
-  int num_nodes = inmsg->btree.getNumNodes();
-  memcpy(buf, &num_nodes, sizeof(int));  // copy numnodes into buffer
-  buf = buf + sizeof(int);               // don't overwrite numnodes
-  // copies into buffer, give size of buffer minus header
-  inmsg->btree.Flatten((void*)buf, treesize);    
-  buf = buf - sizeof(int);              // don't lose numnodes
-  delete inmsg;
-  return (void*) buf;
-\}
-
-PackedMessage*
-PackedMessage::unpack(void* inbuf)
-\{
-  // inbuf is the raw memory allocated and assigned in pack
-  char* buf = (char*) inbuf;
-  int num_nodes;
-  memcpy(&num_nodes, buf, sizeof(int));
-  buf = buf + sizeof(int);
-  // allocate the message through charm kernel
-  PackedMessage* pmsg = 
-    (PackedMessage*)CkAllocBuffer(inbuf, sizeof(PackedMessage));
-  // call "inplace" constructor of PackedMessage that calls constructor
-  // of PackedMessage using the memory allocated by CkAllocBuffer,
-  // takes a raw buffer inbuf, the number of nodes, and constructs the btree
-  pmsg = new ((void*)pmsg) PackedMessage(buf, num_nodes);  
-  CkFreeMsg(inbuf);
-  return pmsg;
-\}
-... 
-PackedMessage* pm = new PackedMessage();  // just like always 
-pm->btree.Insert('A');
-...
-\end{alltt}
-
-
-While serializing an arbitrary data structure into a flat buffer, one must be
-very wary of any possible alignment problems.  Thus, if possible, the buffer
-itself should be declared to be a flat struct.  This will allow the \CC\
-compiler to ensure proper alignment of all its member fields.
 
 \subsubsection{Messages with Variable Length Arrays}
 \label{varsize messages}
@@ -306,37 +167,9 @@ class mtype : public CMessage_mtype \{
 \};
 \end{alltt}
 
-\tiny
+\small
 \hrule
 
-The \charmpp{} interface translator generates implementation for three static
-methods for the message class \uw{CMessage\_mtype}. These methods have the
-prototypes:
-
-\begin{alltt}
-    static void* alloc(int msgnum, size_t size, int* array, int priobits);
-    static void* pack(mtype*);
-    static mtype* unpack(void*);
-\end{alltt}
-
-One may choose not to use the translator-generated methods and may override
-these implementations with their own \uw{alloc}, \uw{pack} and \uw{unpack}
-static methods of the \uw{mtype} class.  The \kw{alloc} method will be called
-when the message is allocated using the \CC\ \kw{new} operator. The programmer
-never needs to explicitly call it.  Note that all elements of the message are
-allocated when the message is created with \kw{new}. There is no need to call
-\kw{new} to allocate any of the fields of the message. This differs from a
-packed message where each field requires individual allocation. The \kw{alloc}
-method should actually allocate the message using \kw{CkAllocMsg}, whose
-signature is given below:
-
-\begin{alltt}
-void *CkAllocMsg(int msgnum, int size, int priobits); 
-\end{alltt}  
-
-\hrule
-\normalsize
-
 \noindent\textbf{An Example}
 
 Suppose a \charmpp\ message contains two variable length arrays of types
@@ -384,13 +217,68 @@ The interface translator generates the \uw{CMessage\_VarsizeMessage} class,
 which contains code to properly allocate, pack and unpack the
 \uw{VarsizeMessage}.
 
-\tiny
+
+One can allocate messages of the \uw{VarsizeMessage} class as follows:
+
+\begin{alltt}
+// firstArray will have 4 elements
+// secondArray will have 5 elements 
+VarsizeMessage* p = new(4, 5, 0) VarsizeMessage;
+p->firstArray[2] = 13;     // the arrays have already been allocated 
+p->secondArray[4] = 6.7; 
+\end{alltt}
+
+Another way of allocating a varsize message is to pass a \uw{sizes} in an array
+instead of the parameter list. For example,
+
+\begin{alltt}
+int sizes[2];
+sizes[0] = 4;               // firstArray will have 4 elements
+sizes[1] = 5;               // secondArray will have 5 elements 
+VarsizeMessage* p = new(sizes, 0) VarsizeMessage;
+p->firstArray[2] = 13;     // the arrays have already been allocated 
+p->secondArray[4] = 6.7; 
+\end{alltt}
+
 \hrule
+\normalsize
+
+No special handling is needed for deleting varsize messages.
+
+\subsubsection{Message Packing}
+\label{message packing}
+\index{message packing}
 
-The static methods \texttt{alloc}, \texttt{pack}, and \texttt{unpack} are
-generated by the interface translator for the \uw{CMessage\_VarsizeMessage}
-class. Thus, one is spared from having to write them.  For example, these
-methods for the above class would be similar to:
+The \charmpp{} interface translator generates implementation for three static
+methods for the message class \uw{CMessage\_mtype}. These methods have the
+prototypes:
+
+\begin{alltt}
+    static void* alloc(int msgnum, size_t size, int* array, int priobits);
+    static void* pack(mtype*);
+    static mtype* unpack(void*);
+\end{alltt}
+
+One may choose not to use the translator-generated methods and may override
+these implementations with their own \uw{alloc}, \uw{pack} and \uw{unpack}
+static methods of the \uw{mtype} class.  The \kw{alloc} method will be called
+when the message is allocated using the \CC\ \kw{new} operator. The programmer
+never needs to explicitly call it.  Note that all elements of the message are
+allocated when the message is created with \kw{new}. There is no need to call
+\kw{new} to allocate any of the fields of the message. This differs from a
+packed message where each field requires individual allocation. The \kw{alloc}
+method should actually allocate the message using \kw{CkAllocMsg}, whose
+signature is given below:
+
+\begin{alltt}
+void *CkAllocMsg(int msgnum, int size, int priobits); 
+\end{alltt}  
+
+
+For varsize messages, these static methods \texttt{alloc}, \texttt{pack}, and 
+\texttt{unpack} are
+generated by the interface translator.  For example, these
+methods for the \kw{VarsizeMessage} class above would be similar to:
 
 \begin{alltt}
 // allocate memory for varmessage so charm can keep track of memory
@@ -442,38 +330,146 @@ are valid \CC\ pointers to the start of the arrays.  After packing, they become
 offsets from the address of the pointer variable to the start of the pointed-to
 data.  Unpacking restores them to pointers. 
 
-\hrule
-\normalsize
+\subsubsection{Custom Packed Messages}
+\index{packed messages}
 
-One can allocate messages of the \uw{VarsizeMessage} class as follows:
+In many cases, a message must store a {\em non-linear} data structure using
+pointers.  Examples of these are binary trees, hash tables etc. Thus, the
+message itself contains only a pointer to the actual data. When the message is
+sent to the same processor, these pointers point to the original locations,
+which are within the address space of the same processor. However, when such a
+message is sent to other processors, these pointers will point to invalid
+locations.
+
+Thus, the programmer needs a way to ``serialize'' these messages
+\index{serialized messages}\index{message serialization}{\em only if} the
+message crosses the address-space boundary.  \charmpp{} provides a way to do
+this serialization by allowing the developer to override the default
+serialization methods generated by the \charmpp{} interface translator.
+Note that this low-level serialization has nothing to do with parameter
+marshalling or the PUP framework described later.
+
+Packed messages are declared in the {\tt .ci} file the same way as ordinary
+messages:
 
 \begin{alltt}
-// firstArray will have 4 elements
-// secondArray will have 5 elements 
-VarsizeMessage* p = new(4, 5, 0) VarsizeMessage;
-p->firstArray[2] = 13;     // the arrays have already been allocated 
-p->secondArray[4] = 6.7; 
+message PMessage;
 \end{alltt}
 
-\tiny
-\hrule
+Like all messages, the class \uw{PMessage} needs to inherit from
+\uw{CMessage\_PMessage} and should provide two {\em static} methods: \kw{pack}
+and \kw{unpack}. These methods are called by the \charmpp\ runtime system, when
+the message is determined to be crossing address-space boundary. The prototypes
+for these methods are as follows:
 
-Another way of allocating a varsize message is to pass a \uw{sizes} in an array
-instead of the parameter list. For example,
+\begin{alltt}
+static void *PMessage::pack(PMessage *in);
+static PMessage *PMessage::unpack(void *in);
+\end{alltt}
+
+Typically, the following tasks are done in \kw{pack} method:
+
+\begin{itemize}
+
+\item Determine size of the buffer needed to serialize message data.
+
+\item Allocate buffer using the \kw{CkAllocBuffer} function. This function
+takes in two parameters: input message, and size of the buffer needed, and
+returns the buffer.
+
+\item Serialize message data into buffer (alongwith any control information
+needed to de-serialize it on the receiving side.
+
+\item Free resources occupied by message (including message itself.)  
+
+\end{itemize}
+
+On the receiving processor, the \kw{unpack} method is called. Typically, the
+following tasks are done in the \kw{unpack} method:
+
+\begin{itemize}
+
+\item Allocate message using \kw{CkAllocBuffer} function. {\em Do not
+use \kw{new} to allocate message here. If the message constructor has
+to be called, it can be done using the in-place \kw{new} operator.}
+
+\item De-serialize message data from input buffer into the allocated message.
+
+\item Free the input buffer using \kw{CkFreeMsg}.
+
+\end{itemize}
+
+Here is an example of a packed-message implementation:
 
 \begin{alltt}
-int sizes[2];
-sizes[0] = 4;               // firstArray will have 4 elements
-sizes[1] = 5;               // secondArray will have 5 elements 
-VarsizeMessage* p = new(sizes, 0) VarsizeMessage;
-p->firstArray[2] = 13;     // the arrays have already been allocated 
-p->secondArray[4] = 6.7; 
+// File: pgm.ci
+mainmodule PackExample \{
+  ...
+  message PackedMessage;
+  ...
+\};
+
+// File: pgm.h
+...
+class PackedMessage : public CMessage_PackedMessage
+\{
+  public:
+    BinaryTree<char> btree; // A non-linear data structure 
+    static void* pack(PackedMessage*);
+    static PackedMessage* unpack(void*);
+    ...
+\};
+...
+
+// File: pgm.C
+...
+void*
+PackedMessage::pack(PackedMessage* inmsg)
+\{
+  int treesize = inmsg->btree.getFlattenedSize();
+  int totalsize = treesize + sizeof(int);
+  char *buf = (char*)CkAllocBuffer(inmsg, totalsize);
+  // buf is now just raw memory to store the data structure
+  int num_nodes = inmsg->btree.getNumNodes();
+  memcpy(buf, &num_nodes, sizeof(int));  // copy numnodes into buffer
+  buf = buf + sizeof(int);               // don't overwrite numnodes
+  // copies into buffer, give size of buffer minus header
+  inmsg->btree.Flatten((void*)buf, treesize);    
+  buf = buf - sizeof(int);              // don't lose numnodes
+  delete inmsg;
+  return (void*) buf;
+\}
+
+PackedMessage*
+PackedMessage::unpack(void* inbuf)
+\{
+  // inbuf is the raw memory allocated and assigned in pack
+  char* buf = (char*) inbuf;
+  int num_nodes;
+  memcpy(&num_nodes, buf, sizeof(int));
+  buf = buf + sizeof(int);
+  // allocate the message through charm kernel
+  PackedMessage* pmsg = 
+    (PackedMessage*)CkAllocBuffer(inbuf, sizeof(PackedMessage));
+  // call "inplace" constructor of PackedMessage that calls constructor
+  // of PackedMessage using the memory allocated by CkAllocBuffer,
+  // takes a raw buffer inbuf, the number of nodes, and constructs the btree
+  pmsg = new ((void*)pmsg) PackedMessage(buf, num_nodes);  
+  CkFreeMsg(inbuf);
+  return pmsg;
+\}
+... 
+PackedMessage* pm = new PackedMessage();  // just like always 
+pm->btree.Insert('A');
+...
 \end{alltt}
 
-\hrule
-\normalsize
 
-No special handling is needed for deleting varsize messages.
+While serializing an arbitrary data structure into a flat buffer, one must be
+very wary of any possible alignment problems.  Thus, if possible, the buffer
+itself should be declared to be a flat struct.  This will allow the \CC\
+compiler to ensure proper alignment of all its member fields.
+
 
 \subsubsection{Prioritized Execution}
 \label{prioritized message passing}
@@ -631,53 +627,9 @@ delivery order} you specify.
 However, it makes a serious attempt to be ``close'', so priorities
 can strongly affect the efficiency of your program.
 
-\subsubsection{Entry Method Attributes}
-\label{attributes}
 
-\charmpp{}  provides a handful of special attributes that \index{entry
-method}entry methods may have.  In order to give a particular \index{entry
-method}entry method an attribute, you must specify the keyword for the desired
-attribute in the attribute list of that entry method's {\tt .ci} file
-declaration.  The syntax for this is as follows:
 
-\begin{alltt}
-entry [attribute1, ..., attributeN] void EntryMethod(MessageType *);
-\end{alltt}
 
-\charmpp{} currently offers four attributes that one may give an entry method:
-\kw{threaded}, \kw{sync}, \kw{exclusive}, and \kw{virtual}.
-
-\index{threaded}Threaded \index{entry method}entry methods are simply entry
-methods which are run in their own nonpremptible threads.  To make an
-\index{entry method}entry method threaded, one simply adds the keyword
-\kw{threaded} to the attribute list of that entry method.
-
-\index{sync}Sync \index{entry method}entry methods are special in that calls to
-sync entry methods are blocking - they do not return control to the caller
-until the method is finished executing completely.  Sync methods may have
-return values; however, they may only return messages.  To make an \index{entry
-method}entry method a sync entry method, add the keyword \kw{sync} to the
-attribute list of that entry method.
-
-\index{exclusive}Exclusive entry methods, which exist only on node groups, are
-\index{entry method}entry methods that do not execute while other exclusive
-\index{entry method}entry methods of its node group are executing in the same
-node.  If one exclusive method of a node group is executing on node 0, and
-another one is scheduled to run on that same node, the second exclusive method
-will wait for the first to finish before it executes.  To make an \index{entry
-method}entry method exclusive, add the keyword \kw{exclusive} to that
-entry method's attribute list.
-
-\index{virtual}Virtual \index{entry method}entry methods are inherited in the
-same manner as virtual methods of sequential \CC{} objects.  For a detailed
-discussion of inheritance in \charmpp{}, refer to section \ref{inheritance and
-templates}.  To make an entry method virtual, just add the keyword \kw{virtual}
-to that method's attribute list.  Additionally, one may make a virtual
-\index{entry method}entry method a pure virtual entry method.  They behave in
-the same way as pure virtual methods in \CC{} and are declared in a very
-similar fashion.  To make a virtual entry method pure, add a ``= 0'' after that
-entry method's {\tt .ci} file declaration.  This looks like the following:
 
-\begin{alltt}
-entry [virtual] void PureVirtualEntry(MessageType *) = 0;
-\end{alltt}
+
+
index 429a3893216e522bf82b711e35f89627493f26a7..07daeb02791567ac7cbf0760e1b3b4da87fc8b83 100644 (file)
@@ -56,10 +56,10 @@ A simple \charmpp\ program is given below:
 // File: pgm.ci
 
 mainmodule Hello \{
-  readonly CkChareID mid;
+  readonly CProxy_HelloMain mainProxy;
   mainchare HelloMain \{
     entry HelloMain(); // implicit CkArgMsg * as argument
-    entry void Wait(void);
+    entry void PrintDone(void);
   \};
   group HelloGroup \{
     entry HelloGroup(void);
@@ -73,7 +73,7 @@ mainmodule Hello \{
 class HelloMain: public Chare \{
   public:
     HelloMain(CkArgMsg *);
-    void Wait(void);
+    void PrintDone(void);
   private:
     int count;
 \};
@@ -87,16 +87,16 @@ class HelloGroup: public Group \{
 // File: pgm.C
 #include "pgm.h"
 
-CkChareID mid;
+CProxy_HelloMain mainProxy;
 
 HelloMain::HelloMain(CkArgMsg *msg) \{
   delete msg;
   count = 0;
-  mid = thishandle;
+  mainProxy=thishandle;
   CProxy_HelloGroup::ckNew(); // Create a new "HelloGroup"
 \}
 
-void HelloMain::Wait(void) \{
+void HelloMain::PrintDone(void) \{
   count++;
   if (count == CkNumPes()) \{ // Wait for all group members to finish the printf
     CkExit();
@@ -105,8 +105,7 @@ void HelloMain::Wait(void) \{
 
 HelloGroup::HelloGroup(void) \{
   ckout << "Hello World from processor " << CkMyPe() << endl;
-  CProxy_HelloMain pself(mid);
-  pself.Wait();
+  mainProxy.PrintDone();
 \}
 
 #include "Hello.def.h" // Include the Charm++ object implementations
@@ -123,15 +122,15 @@ pgm: pgm.ci pgm.h pgm.C
 
 \uw{HelloMain} is designated a \kw{mainchare}. Thus the Charm Kernel starts
 execution of this program by creating an instance of \uw{HelloMain} on
-processor 0. The HelloMain constructor creates a chare group \uw{HelloGroup},
-and stores a handle to itself and returns. The call to create the group returns
-immediately after directing Charm Kernel to perform the actual creation and
-invocation.  Shortly after, the Charm Kernel will create an object of type
-\uw{HelloGroup} on each processor, and call its constructor. The constructor
-will then print ``Hello World...'' and then call the \uw{Wait} method of
-\uw{HelloMain}. The Wait method calls CkExit() after all group members have
-called it (i.e., they have finished printing ``Hello World...''), and the
-\charmpp program exits.
+processor 0. The HelloMain constructor creates a chare group
+\uw{HelloGroup}, and stores a handle to itself and returns. The call to
+create the group returns immediately after directing Charm Kernel to perform
+the actual creation and invocation.  Shortly after, the Charm Kernel will
+create an object of type \uw{HelloGroup} on each processor, and call its
+constructor. The constructor will then print ``Hello World...'' and then
+call the \uw{PrintDone} method of \uw{HelloMain}. The \uw{PrintDone} method
+calls \kw{CkExit} after all group members have called it (i.e., they have
+finished printing ``Hello World...''), and the \charmpp program exits.
 
 \subsubsection{Functions in the ``decl.h'' and ``def.h'' files}
 
index cfaa25dddd1888894772695414c5add4b9475a9f..1aef3261c41f10fd8d1834d7ecd85d3283886872 100644 (file)
@@ -1,6 +1,6 @@
 \subsection{Nodegroup Objects}
 
-{\it Node groups}\experimental{} \index{node groups} \index{nodegroup} are very
+{\it Node groups} \index{node groups} \index{nodegroup} are very
 similar to the group objects already discussed in that node groups are
 collections of chares as well.  Node groups, however, have one chare per node
 rather than one chare per processor.  So, each node contains a branch of the
index 2165cf0343655abec2a159fddeda63e53dafa858..c6c02f59b038e68898445a750ecb0ce9c1af1271 100644 (file)
@@ -1,19 +1,20 @@
 \subsection{\kw{initcall} routines}
+\experimental{}
 Some registration routines need be executed exactly once
 on every processor before the computation begins.
-By declaring a regular \CC subroutine \index{initcall}
+By declaring a regular \CC\ subroutine \index{initcall}
 \kw{initcall} in the .ci file, you ask \charmpp to execute 
-the routine exactly once on every processor before the
+the routine exactly once on every node before the
 computation begins.
 
 \begin{alltt}
-module foo {
+module foo \{
     initcall void fooGlobalInit(void);
-    chare bar {
+    chare bar \{
         ...
         initcall void barInit(void);
-    };
-};
+    \};
+\};
 \end{alltt}
 
 This code will execute the routines \uw{fooGlobalInit} and
index ad7e66e9734fee1cfff0a2a2bba8c29fa4de7592..0239ca970b7cdcd81e8d638e25602eb4e6bf94e1 100644 (file)
@@ -1,56 +1,53 @@
 \section{\charmpp{} Overview}
 
 We think that \charmpp\ is easy to use if you are familiar with object-based
-programming. (But of course that is our opinion, if your opinion differs, you
-are encouraged to let us know the reasons, and features that you would like to
-see in \charmpp.) Object-based programming is built around the concept of
-``encapsulation'' of data. As implemented in \CC, data encapsulation is
-achieved by grouping together data and methods (or functions, or subroutines,
-or procedures, or other such entities) inside of an object. A class is a
-blueprint for an object.  The encapsulated data is said to be ``private'' to
-the object, and only the methods of that class can manipulate that data. A
-method that has the same name as the class is a ``blessed'' method, called a
-``Constructor'' for that class.  Constructor method is typically responsible
-for initializing the encapsulated data of an object. Each method, including the
-constructor can optionally be supplied data in the form of parameters (or
-arguments). In \CC, one can create objects with the {\tt new} operator that
-returns a pointer to the object. This pointer can be used to refer to the
-object, and call methods on that object.
-
-\charmpp{} is built on top of \CC, and also based on ``encapsulation''. Similar
-to \CC, \charmpp\ entities can contain private data, and public methods. The
-major difference is that these methods can be invoked from remote processors
-asynchronously.  Asynchronous method invocation implies that the caller does
-not wait for the method to be actually executed and does not wait for the
-method's return value. Therefore, \charmpp\ methods (called entry methods) do
-not have a return value\footnote{Asynchronous remote method invocation is the
-core of \charmpp. However, to simplify programming, \charmpp\ makes use of the
-interoperable nature of its runtime system, and combines seemlessly with
-user-level threads to also support synchronous method execution, albeit with a
-slight overhead of thread creation and scheduling.}. Since the actual \charmpp\
-object on which the method is being invoked is possibly on a remote processor,
-in possibly different address space, the \CC\ way of referring to an object,
-such as a pointer, is not valid in \charmpp.  Instead, there are two ways of
-referring to a remote object in \charmpp. First, every remote object has a
-unique {\em handle} called \kw{ChareID}. This is a C struct that uniquely
-defines the location of the object on the parallel machine. Note that, whatever
-the type of object (its class), it has the same kind of such handle. The
-second, and preferred way of referring to a remote object is its ``proxy''.
-
-Those familiar with various component models in the distributed computing world
-will recognize ``proxy'' to be a dummy entity that refers to the actual
-entity. It is exactly that way in \charmpp\ too. For each object type (each
-class), its ``proxy'' class exists (actually it is generated by the ``interface
-translator''), which contains an actual reference to the class (such as a \kw{
-ChareID}). Furthermore, the methods of this ``proxy'' class correspond to the
-methods of actual class, and act as ``forwarders''. That is, when one invokes a
-method on a proxy to a remote object, the proxy forwards this method invocation
-to the actual remote object. Creation of a proxy results in creation of a new
+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
+like to see in \charmpp.) Object-based programming is built around the
+concept of ``encapsulation'' of data. As implemented in \CC, data
+encapsulation is achieved by grouping together data and methods (also known
+as functions, subroutines, or procedures) inside of an object.
+
+A class is a blueprint for an object.  The encapsulated data is said to be
+``private'' to the object, and only the methods of that class can manipulate
+that data. A method that has the same name as the class is a ``blessed''
+method, called a ``Constructor'' for that class.  A constructor method is
+typically responsible for initializing the encapsulated data of an object.
+Each method, including the constructor can optionally be supplied data in
+the form of parameters (or arguments). In \CC, one can create objects with
+the {\tt new} operator that returns a pointer to the object. This pointer
+can be used to refer to the object, and call methods on that object.
+
+\charmpp{} is built on top of \CC, and also based on ``encapsulation''.
+Similar to \CC, \charmpp\ entities can contain private data, and public
+methods. The major difference is that these methods can be invoked from
+remote processors asynchronously.  Asynchronous method invocation means that
+the caller does not wait for the method to be actually executed and does not
+wait for the method's return value. Therefore, \charmpp\ methods (called
+entry methods) do not have a return value\footnote{Asynchronous remote
+method invocation is the core of \charmpp. However, to simplify programming,
+\charmpp\ makes use of the interoperable nature of its runtime system, and
+combines seamlessly with user-level threads to also support synchronous
+method execution, albeit with a slight overhead of thread creation and
+scheduling.}. Since the actual \charmpp\ object on which the method is being
+invoked may be on a remote processor\footnote{With its own, different address
+space}, the \CC\ way of referring to an object, via a pointer, is not valid
+in \charmpp.  Instead, we refer to a remote chare via a ``proxy''.
+
+Those familiar with various component models\footnote{Such as CORBA} in the
+distributed computing world will recognize ``proxy'' to be a dummy, standin
+entity that refers to an actual entity.  For each chare type, a ``proxy''
+class exists\footnote{The proxy class is generated by the ``interface
+translator'' based on a description of the entry methods}.  The methods of
+this ``proxy'' class correspond to the remote methods of actual class, and
+act as ``forwarders''. That is, when one invokes a method on a proxy to a
+remote object, the proxy forwards this method invocation to the actual
 remote object. All entities that are created and manipulated remotely in
-\charmpp\ have such proxies. Proxies for each type of entity in \charmpp\ have
-some differences among the features they support, but the basic syntax and
-semantics almost always remains the same, and that is of invoking methods on
-the remote object by invoking methods on proxies.
+\charmpp\ have such proxies. Proxies for each type of entity in \charmpp\
+have some differences among the features they support, but the basic syntax
+and semantics remains the same-- that of invoking methods on the remote
+object by invoking methods on proxies.
+
 
 \subsection{\charmpp\ Execution Model}
 
@@ -65,15 +62,16 @@ another to invoke methods asynchronously.  Conceptually, the system maintains a
 ``work-pool'' consisting of seeds for new \index{chare}chares, and
 \index{message}messages for existing chares. The runtime system (called {\em
 Charm Kernel}) may pick multiple items, non-deterministically, from this pool
-and execute them.  It will not process two messages for the same
-\index{chare}chare concurrently, but otherwise it is free to schedule them in
-any way.
+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 a pointer to a
-message object, or no parameters.  Since \index{chare}chares can be created on
-remote processors, obviously some constructor of a chare needs to be an entry
-method.
+\index{entry method}{\em entry} methods.  Entry methods may take marshalled
+paramters, 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
@@ -85,36 +83,38 @@ need to name a chares' processor, chares can potentially migrate from one
 processor to another.  (This behaviour is used by the dynamic load-balancing
 framework for chare containers, such as arrays.)
 
-Other \charmpp\ objects are collections of chares. They are: \index{group}{\em
-chare-groups}, \index{nodegroup}{\em chare-nodegroups}, and \index{array}{\em
-chare-arrays}, referred to as {\em groups}, {\em nodegroups}, and {\em arrays}
-throughout this manual. A group (nodegroup) is a collection of chares, one per
-processor (SMP node), that is addressed using a unique system-wide name. An
-array is a collection of arbitrary number of migratable chares, mapped to
-processors according to a user-defined map group.
-
-Every \charmpp\ program must have at least one \kw{mainchare}.  There can be
-only one instance of this, which is created on processor 0 when the \charmpp\
-program starts up.  Execution of a \charmpp\ program begins with Charm Kernel
-constructing all the designated \kw{mainchare}s.  Typically, the \kw{mainchare}
-constructor starts the computation by creating other chares and chare
-\index{group} groups.  It can also be used to initialize shared \kw{readonly}
+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.  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 about the types of \index{chare}chares
-in the user program, the methods that can be invoked on these chares from
-remote processors, the arguments these methods take as input etc. Therefore,
-when the program starts up, these user-defined entities need to be registered
-with Charm Kernel, which assigns a unique identifier to each of them. While
-invoking a method on a remote object, these identifiers need to be specified to
-Charm Kernel. Registration of user-defind entities, and maintaining these
-identifiers can be cumbersome. Fortunately, it can be done by the \charmpp\
-interface translator. The \charmpp\ interface translator generates definitions
-for {\em proxy} objects. A proxy object acts as a {\em handle} to a remote
-chare. One invokes methods on a proxy object, which in turn carries out remote
-method invocation on the chare.
+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 b registered with Charm Kernel, which assigns a unique
+identifier to each of them. While invoking a method on a remote object,
+these identifiers need to be specified to Charm Kernel. Registration of
+user-defind entities, and maintaining these identifiers can be cumbersome.
+Fortunately, it 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
@@ -123,14 +123,12 @@ allow entry methods to be executed in separate user-level threads.  These
 making {\em synchronous} calls to remote object methods that return results in
 messages.
 
-\charmpp\ program execution is terminated by the \kw{CkExit} call. This call is
-not the same as in Unix: it merely informs the Charm Kernel that all
-computations on all processors must be terminated, and then returns to the user
-program: the programmer should make sure that no work is done by the method
-after \kw{CkExit} is called.  Charm Kernel ensures that no messages are
-processed and no entry methods are called after the currently executing entry
-method completes. \kw{CkExit} need not be called on all processors; it is
-enough to call it from just one processor at the end of the computation.
+\charmpp\ program execution is terminated by the \kw{CkExit} call.  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}
 
@@ -138,37 +136,35 @@ This section describes various entities in a typical \charmpp\ program.
 
 \subsubsection{Sequential Objects}
 
-A \charmpp\ program typically contains a number of sequential objects. These
-objects are similar to the objects in \CC, except that they {\em should not
-have any static data members}\footnote{ This restriction makes \charmpp\
-programs portable across distributed and shared memory architectures, as well
-as clusters of shared memory multiprocessors. If one feels that these
-restrictions are too severe, one is encouraged to look at the portability
-macros of Converse, that make it possible to write portable programs in
-presence of global or static variables.}. These objects are created
-synchronously on the local processor (using a {\tt new} operator in \CC), and
-their methods could be synchronously invoked only from the local processor.
-These objects are not known to the \charmpp\ runtime system, and thus they need
-not be mentioned in the module interface files.
+A \charmpp\ program typically consists mostly of ordinary sequential \CC
+code and objects. Such entities are only accessible locally, are not known
+to the \charmpp\ runtime system, and thus need not be mentioned in the
+module interface files. 
+
+\charmpp\ does not affect the syntax or semantics of such \CC\ entities,
+except that changes to global variables (or static data members of a class)
+on one node will not be visible on other nodes.  Global data changes
+must be explicitly sent between processors.  For processor- and
+thread-private storage, refer to the ``Global Variables'' section
+of the Converse manual.
+
 
 \subsubsection{Messages}
 
 Messages supply data arguments to the asynchronous remote method invocation.
 These objects are treated differently from other objects in \charmpp\ by the
-runtime system, and therefore they must be specified in the interface file of
-the module.  With parameter marshalling, the system creates and handles
-the message completely internally.
-Other messages are instances of \CC\ classes that are subclassed from a
-special class that is generated by the \charmpp\ interface translator.  Another
-variation of communication objects is conditionally packed and unpacked. This
-variation should be used when one wants to send messages that contain pointers
-to the data rather than the actual data to other processors. This type of
-communication objects contains two methods: \kw{pack}, and \kw{unpack}.  These
-messages are specified differently in the interface file for the module.  The
-third variation of communication objects is called {\em varsize} messages.
-Varsize messages is an effective optimization on conditionally packed messages,
-and have to be made known to the \charmpp\ runtime using a special keyword in
-the interface file.
+runtime system, and therefore they must be specified in the interface file
+of the module.  With parameter marshalling, the system creates and handles
+the message completely internally. Other messages are instances of \CC\
+classes that are subclassed from a special class that is generated by the
+\charmpp\ interface translator.  Another variation of communication objects
+is conditionally packed and unpacked. This variation should be used when one
+wants to send messages that contain pointers to the data rather than the
+actual data to other processors. This type of communication objects contains
+two static methods: \kw{pack}, and \kw{unpack}. The third variation of
+communication objects is called {\em varsize} messages. Varsize messages is
+an effective optimization on conditionally packed messages, and can be
+declared with special syntax in the interface file.
 
 \subsubsection{Chares}
 
@@ -190,6 +186,23 @@ have its constuctors as entry methods (with at most one message pointer
 parameter). These chares and their entry methods have to be specified in the
 interface file.
 
+\subsubsection{Chare Arrays}
+
+Chare arrays are collections of chares. However, unlike chare groups or
+nodegroups, arrays are not constrained by characteristics of the underlying
+parallel machine such as number of processors or nodes. Thus, chare arrays
+can have any number of {\em elements}. The array elements themselves are
+chares, and methods can be invoked on individual array elements as usual.  
+Each element of an array has a globally unique index, and messages are
+addressed to that index.
+
+Unlike other entities in \charmpp\, the dynamic load balancing framework (LB
+Framework) treats array elements as objects that can be migrated across
+processors. Thus, the runtime system keeps track of computational load
+across the system, and also the time spent in execution of entry methods on
+array elements, and then employs one of several strategies to redistribute
+array elements across the available processors.
+
 \subsubsection{Chare Groups}
 
 Chare Groups\footnote{ These were called Branch Office Chares (BOC) in earlier
@@ -226,22 +239,3 @@ problems by allowing the programmer to specify an entry method of a nodegroup
 to be {\em exclusive}, thus guaranteeing that no other {\em exclusive} method
 of that nodegroup member can execute simultaneously within the node.
 
-\subsubsection{Chare Arrays}
-
-Chare arrays are collections of chares. However unlike chare groups or
-nodegroups, arrays are not constrained by characteristics of the underlying
-parallel machine such as number of processors or nodes. Thus, chare arrays can
-have any number of {\em elements}. The array elements themselves are chares,
-and methods can be invoked on individual array elements as usual. However, what
-distinguishes chare arrays from the other entities in \charmpp\ is that the
-dynamic load balancing framework in \charmpp\ (LB Framework) treats them as
-objects that can be migrated across processors. Thus, the runtime system keeps
-track of computational load across the system, and also the time spent in
-execution of entry methods on array elements, and then employs some smart
-strategies to redistribute array elements across the available processors.
-Chare arrays is a recent addition to \charmpp\ in response to various dynamic
-and irregular applications of parallel computing. Currently, chare arrays are
-implemented as a library on top of the Charm kernel. However, the \charmpp\
-interface translator recognizes them and has special syntax for describing
-them.
-
index fbda50acb6606c60bcea140d3a4cf13db964cff1..3d840acc52d93dc95b71050613129cdef3ad1890 100644 (file)
@@ -10,7 +10,7 @@ Like many \CC\ concepts, the PUP framework is easier to use than
 describe: 
 
 \begin{alltt}
-class foo {
+class foo \{
  private:
     double a;
     int x;
@@ -21,12 +21,12 @@ class foo {
     ...other methods...
 
     //pack/unpack routine: describe my fields to charm++
-    void pup(PUP::er &p) {
+    void pup(PUP::er &p) \{
       p(a);
       p(x);p(y);p(z);
       p(q,3);
-    }
-};
+    \}
+\};
 PUPmarshall(foo); //<- for passing foo's as marshalled parameters
 \end{alltt}
 
@@ -101,7 +101,7 @@ these need to be allocated (in the usual way) before you pup them.
 Deallocation should be left to the class destructor as usual.
 
 \begin{alltt}
-class bar {
+class bar \{
 private:
     foo *f; /*Heap-allocated foo object*/
     int n;
@@ -109,10 +109,10 @@ private:
 public:
     ...other methods...
     //Destructor is the usual
-    ~bar() {free(arr);delete f;}
+    ~bar() \{free(arr);delete f;\}
     
     //pack/unpack: describe my fields to Charm++
-    void pup(PUP::er &p) {
+    void pup(PUP::er &p) \{
       if (p.isUnpacking()) 
          f=new foo;
       f->pup(p);//pup f's fields
@@ -121,8 +121,8 @@ public:
       if (p.isUnpacking()) 
          arr=(double *)malloc(sizeof(double)*n);
       p(arr,n);//pup array data
-    }
-};
+    \}
+\};
 PUPmarshall(bar); //<- for passing foo's as marshalled parameters
 \end{alltt}
 
@@ -150,38 +150,39 @@ For example,
    initcall void parentChildInit(void);
 
 //In the .h file:
-class parent : public PUP::able {
+class parent : public PUP::able \{
     ... data members ...
 public:
     ... other methods ...
-    parent() {...}
-    parent(CkMigrateMessage *m) : PUP::able(m) {}
-    virtual void pup(PUP::er &p) {
+    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 ...
-    }
+    \}
     PUPable\_decl(parent);    
-};
-class child : public parent {
+\};
+class child : public parent \{
     ... more data members ...
 public:    ... more methods, possibly virtual ...
-    child() {...}
-    child(CkMigrateMessage *m) : parent(m) {}
-    virtual void pup(PUP::er &p) {
+    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 ...
-    }
+    \}
     PUPable\_decl(child);    
-};
+\};
 
 //Somewhere in a .C file:
 PUPable\_def(parent);
 PUPable\_def(child);
+
 void parentChildInit(void)
-{//Called once on each processor
+\{//Called once on each processor
     PUPable\_reg(parent);
     PUPable\_reg(child);
-}
+\}
 \end{alltt}
 
 These declarations supercede the \kw{PUPmarshall} declaration 
@@ -192,18 +193,18 @@ allocate and pup a pointer to a parent or child
 using the vertical bar \kw{PUP::er} syntax:
 
 \begin{alltt}
-class keepsParent {
-    parent *obj; //May actually point to a child class
+class keepsParent \{
+    parent *obj; //May actually point to a child class (or be NULL)
 public:
     ...
-    ~keepsParent() {
+    ~keepsParent() \{
         delete obj;
-    }
+    \}
     void pup(PUP::er &p) 
-    {
+    \{
         p|obj;
-    }
-};
+    \}
+\};
 \end{alltt}
 
 This will properly pack, allocate, and unpack obj whether
@@ -216,22 +217,22 @@ For example, if the nodes of a binary tree are \kw{PUP::able},
 one may write the tree's pup routine easily:
 
 \begin{alltt}
-class treeNode : public PUP::able {
+class treeNode : public PUP::able \{
     treeNode *left;//Left subtree
     treeNode *right;//Right subtree
     ... other fields ...
 public:
     ... usual PUP::able support: ...
-    treeNode(CkMigrateMessage *m) : PUP::able(m) {}
-    ~treeNode() {delete left; delete right;}
-    void pup(PUP::er &p) {
+    treeNode(CkMigrateMessage *m) : PUP::able(m) \{\}
+    ~treeNode() \{delete left; delete right;\}
+    void pup(PUP::er &p) \{
         PUP::able::pup(p);//Call base class
         p|left;
         p|right;
         ... pup other fields as usual ...
-    }
+    \}
     PUPable\_decl(treeNode);
-};
+\};
 \end{alltt}
 
 This same implementation will work properly if the tree's
@@ -276,25 +277,25 @@ 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
+  \{//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
+  \{//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
index 2dfbda4f82216154bca9fad9ee9883f55cdb29d8..b1e055320f073a3b960c7947b3070570a29044cc 100644 (file)
@@ -13,39 +13,25 @@ and a handle to the chare on which that entry function should be called.  The
 syntax of this call looks like this:
 
 \begin{alltt}
- CkStartQD(int Index, CkChareID* chareID);
+ CkStartQD(int Index,const CkChareID* chareID);
 \end{alltt}
 
 To retrieve the corresponding index of a particular \index{entry method}entry
-method, you must use a static method contained within the \uw{CProxy} object
+method, you must use a static method contained within the \uw{CkIndex} object
 corresponding to the \index{chare}chare containing that entry method.  The
 syntax of this call is as follows:
 
 \begin{alltt}
-CProxy_ChareName::ckIdx_EntryMethod(Msg *Message);
+\kw{myIdx}=CkIndex_\uw{ChareName}::\uw{EntryMethod}(\uw{parameters});
 \end{alltt}
 
-where \uw{chareID} is the name of the chare identifier of the chare containing
+where \uw{ChareName} is the name of the chare containing
 the desired entry method, \uw{EntryMethod} is the name of that entry method,
-and \uw{Message} is a pointer to the kind of message that the desired entry
-method takes as a parameter. To make this look a little cleaner, we have
-provided a simple macro called \kw{EntryIndex}, which can be used in the place
-of this convoluted looking static method call.  \kw{EntryIndex} takes as
-parameters the type of chare in which the entry method is located, the name of
-the entry method itself, and the type of message that the entry method takes as
-a parameter. For example:
+and \uw{parameters} are the parameters taken by the method.
+These parameters are only used to resolve the proper \uw{EntryMethod};
+they are otherwise ignored.
 
-\begin{alltt}
- EntryIndex(ChareName, EntryName, MsgName);
-\end{alltt}
-
-Note that \uw{ChareName}, \uw{EntryName}, and \uw{MsgName} are {\bf NOT}
-variables or constants. This is text that the preprocessor uses to fill in
-portions of the previously mentioned static method call.  Additionally, this
-macro method will not work with templated chares (refer to Section
-~\ref{inheritance and templates} for details on templated chares).
-
-\kw{CkWaitQD}, however, does not register a callback.  Rather,
+\kw{CkWaitQD}, by contrast, does not register a callback.  Rather,
 \kw{CkWaitQD} blocks and does not return until \index{quiescence}quiescence is
 detected.  It takes no parameters and returns no value.  A call to
 \kw{CkWaitQD} simply looks like this: 
diff --git a/doc/charm++/seqobjs.tex b/doc/charm++/seqobjs.tex
deleted file mode 100644 (file)
index ef323b7..0000000
+++ /dev/null
@@ -1,6 +0,0 @@
-\subsection{Sequential Objects}
-\index{sequential objects} 
-
-These are the same as \CC{} classes and functions.  All \CC{} features can
-be used.  However, care needs to be taken when sequential objects
-interact with \charmpp\ objects.