docs: Simplify and modernize text on chares and chare creation
authorAaron Becker <akbecker@gmail.com>
Mon, 23 Jul 2012 22:36:19 +0000 (17:36 -0500)
committerAaron Becker <akbecker@gmail.com>
Mon, 23 Jul 2012 22:38:28 +0000 (17:38 -0500)
doc/charm++/chares.tex
doc/charm++/messages.tex
doc/charm++/overview.tex

index a2cc6e6296f5b3df715e61f1dbd3c87ac4673229..91382b43446c05c20ea51d6cd18f49a99f039404 100644 (file)
@@ -1,37 +1,44 @@
 \subsection{Chare Objects}
 
 \index{chare}Chares are concurrent objects with methods that can be invoked
-remotely.  These methods are known as \index{entry method}entry methods, and 
-must be specified in the interface (\texttt{.ci}) file:
+remotely. These methods are known as \index{entry method}entry methods. All
+chares must have a constructor that is an entry method, and may have any
+number of other entry methods. All chare classes and their entry methods are
+declared in the interface (\texttt{.ci}) file:
 
 \begin{alltt}
 chare ChareType
 \{
-    entry   ChareType             (\uw{parameters1});
-    entry   void EntryMethodName2 (\uw{parameters2});
+    entry ChareType(\uw{parameters1});
+    entry void EntryMethodName(\uw{parameters2});
 \};
 \end{alltt}
 
+Although it is declared in an interface file, a chare is a \CC object and must
+have a normal \CC implementation in addition to its interface file. A chare
+class {\tt ChareType} must inherit from the class {\tt CBase_ChareType}, which
+is a special class that is generated by the \charmpp translator from the
+interface file.
+
 A corresponding \index{chare}chare definition in the \texttt{.h} file would 
 have the form:
 
 \begin{alltt}
    class ChareType : public CBase\_ChareType \{
-        // Data and member functions as in C++ 
-        // One or more entry methods definitions of the form: 
-   public: 
-      ChareType(\uw{parameters2}) 
-         \{ // C++ code block  \} 
-      void EntryMethodName2(\uw{parameters2}) 
-         \{ // C++ code block  \} 
+       // Data and member functions as in C++
+       // One or more entry methods definitions of the form:
+       public:
+           ChareType(\uw{parameters2});
+           void EntryMethodName2(\uw{parameters2});
    \};
 \end{alltt}
 
 \index{chare}
-Chares are concurrent objects encapsulating medium-grained units of
-work.  Chares can be dynamically created on any processor; there may
+Each chare encapsulates data associated with medium-grained units of work in a
+parallel application.
+Chares can be dynamically created on any processor; there may
 be thousands of chares on a processor. The location of a chare is
-usually determined by the dynamic load balancing strategy; however,
+usually determined by the dynamic load balancing strategy. However,
 once a chare commences execution on a processor, it does not migrate
 to other processors\footnote{Except when it is part of an array.}.  
 Chares do not have a default ``thread of
@@ -40,16 +47,25 @@ chare execute in a message driven fashion upon the arrival of a
 message\footnote{Threaded methods augment this behavior since they execute in
 a separate user-level thread, and thus can block to wait for data.}.
 
-The entry method definition specifies a function that is executed {\em
-without interruption} when a message is received and scheduled for
-processing. Only one message per chare is processed at a time.  Entry
-methods are defined exactly as normal \CC{} function members, except
-that they must have the return value \kw{void} (except for the
-constructor entry method which may not have a return value, and for a 
-{\em synchronous} entry method, which is invoked by a {\em threaded} 
-method in a remote chare) and they
-must have exactly one argument which is a pointer to a message.
-
+The entry method definition specifies a function that is executed {\em without
+interruption} when a message is received and scheduled for processing. Only one
+message per chare is processed at a time.  Entry methods are defined exactly as
+normal \CC{} function members, except that they must have the return value
+\kw{void} (except for the constructor entry method which may not have a return
+value, and for a {\em synchronous} entry method, which is invoked by a {\em
+threaded} method in a remote chare). Each entry method can either take no
+arguments, take a list of arguments that the runtime system can automatically
+pack into a message and send (see section~\ref{marshalling}), or take a single
+argument that is a pointer to a \charmpp message (see section~\ref{messages}).
+
+A chare's entry methods can be invoked via {\it proxies} (see
+section~\ref{proxies}). Proxies to a chare of type {\tt chareType} have type
+{\tt CProxy_chareType}. By inheriting from the CBase parent class, each chare
+gets a {\tt thisProxy} member variable, which holds a proxy to itself. This
+proxy can be sent to other chares, allowing them to invoke entry methods on this
+chare.
+
+\zap{
 Each chare instance is identified by a {\em handle} \index{handle}
 which is essentially a global pointer, and is unique across all
 processors.  The handle of a chare has type \kw{CkChareID}.  The
@@ -63,126 +79,59 @@ for the superclass \kw{Chare} instead of \kw{CBase}\_\uw{ClassType}, although
 this form is not suggested.
 \kw{thishandle} can be used to set fields in a message. This  
 mechanism allows chares to send their handles to other chares.
+}
 
 \subsubsection{Chare Creation}
 
 \label{chare creation}
 
-First, a \index{chare}chare needs to be declared, both in \texttt{.ci} file and
-in \texttt{.h} file, as stated earlier. The following is an example of
-declaration for a \index{chare}chare of user-defined type \uw{C}, where \uw{M1}
-and \uw{M2} are user-defined \index{message}message types, and \uw{someEntry}
-is an entry method.
-
-In the \texttt{mod.ci} file we have:
+Once you have declared and defined a chare class, you will want to create some
+chare objects to use. Chares are created by the {\tt ckNew} method, which is a
+static method of the chare's proxy class:
 
 \begin{alltt}
-module mod \{
-  chare C \{
-    entry C(\uw{parameters});
-    entry void someEntry(\uw{parameters});
-  \};
-\}
+   CProxy_chareType::ckNew(\uw{parameters}, int destPE);
 \end{alltt}
 
-and in the \texttt{mod.h} file:
-
-\begin{alltt}
-#include "mod.decl.h"
-class C : public CBase\_C \{
-  public:
-    C(\uw{parameters});
-    void someEntry(\uw{parameters});
-\};
-\end{alltt}
-
-Now one can use the class \kw{CProxy}\_\uw{chareType} to create a new instance
-of a \index{chare}chare.  Here \uw{chareType} gets replaced with whatever
-\index{chare}chare type we want.  For the above example, proxies would be of
-type \kw{CProxy}\_\uw{C}. A number of \index{chare}chare creation calls exist
-as static or instance methods of class \kw{CProxy}\_\uw{chareType}:
-
-\begin{alltt}
-   CProxy_chareType::ckNew(\uw{parameters}, CkChareID *vHdl, int destPE);
-\end{alltt}
-
-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{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
-argument can be used if the user desires to have a {\em virtual} handle
-\index{virtual handle} to the instance of the \index{chare}chare that will be
-created. This handle is useful for sending \index{message}messages to the
-\index{chare}chare, even though it has not yet been created on any processor.
-Messages sent to this virtual handle are either queued up to be sent to the
-\index{chare}chare after it has been created, or simply redirected if the
-\index{chare}chare has already been created. For performance reasons,
-therefore, virtual handles should be used only when absolutely necessary.
-Virtual handles are otherwise like normal \index{handle}handles, and may be
-sent to other processors in \index{message}messages.  
-
-\item \uw{destPE}: when a \index{chare}chare is to be created at a specific
-processor, the \uw{destPE} is used to specify that processor.  Note that, in
-general, for good \index{load balancing}load balancing, the user should let
-\charmpp{} determine the processor on which to create a \index{chare}chare.
-Under unusual circumstances, however, the user may want to choose the
-destination processor.  If a process replicated on every processor is desired,
-then a \index{chare group}chare group should be used.  If no particular
-processor is required, the parameter can be omitted, or \kw{CK\_PE\_ANY}.
-
-\end{itemize}
+The {\tt parameters} correspond to the parameters of the chare's constructor.
+Even if the constructor takes several arguments, all of the arguments should be
+passed in order to {\tt ckNew}. If the constructor takes no arguments, the
+parameters are omitted. By default, the new chare's location is determined by
+the runtime system. However, this can be overridden by passing a value for
+{\tt destPE}, which specifies the PE where the chare will be created.
 
 The \index{chare}chare creation method deposits the \index{seed}{\em seed} for
 a chare in a pool of seeds and returns immediately. The \index{chare}chare will
 be created later on some processor, as determined by the dynamic \index{load
-balancing}load balancing strategy. When a \index{chare}chare is created, it is
-initialized by calling its   \index{constructor}constructor \index{entry
-method}entry method with the \index{message}message parameter specified to the
-\index{chare}chare creation method.  The method operator does not return any
-value but fills in the \index{virtual handle}virtual handle to the newly
-created \index{chare}chare if specified.
+balancing}load balancing strategy (or by {\tt destPE}).
+When a \index{chare}chare is created, it is
+initialized by calling its \index{constructor}constructor \index{entry
+method}entry method with the parameters specified by {\tt ckNew}.
 
-The following are some examples on how to use the \index{chare}chare creation
-method to create chares.
+Suppose we have declared a chare class {\tt C} with a constructor that takes two
+arguments, an {\tt int} and a {\tt double}.
 
 \begin{enumerate}
 \item{This will create a new \index{chare}chare of type \uw{C} on {\em any}
-processor:}
+processor and return a proxy to that chare:}
 
 \begin{alltt}
-   CProxy_C chareProxy = CProxy_C::ckNew(\uw{parameters});
+   CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0);
 \end{alltt} 
 
 \item{This will create a new \index{chare}chare of type \uw{C} on processor
-\kw{destPE}:}
-
-\begin{alltt}
-   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}:}
+\kw{destPE} and return a proxy to that chare:}
 
 \begin{alltt}
-   CkChareID cid;
-   CProxy_C::ckNew(\uw{parameters}, \&cid, destPE);
-   CProxy_C chareProxy(cid);
+   CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0, destPE);
 \end{alltt}
 
 \end{enumerate}
 
 \subsubsection{Method Invocation on Chares}
 
-A message \index{message} may be sent to a \index{chare}chare using the
-notation:
+A message \index{message} may be sent to a \index{chare}chare through a proxy
+object using the notation:
 
 \begin{tabbing}
 chareProxy.EntryMethod(\uw{parameters})
@@ -198,8 +147,7 @@ message.
 
 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.
+to the chare if it exists on the local processor, and NULL otherwise.
 
 \begin{alltt}
 C *c=chareProxy.ckLocal();
@@ -207,14 +155,3 @@ if (c==NULL) //...is remote-- send message
 else //...is local-- directly use members and methods of c
 \end{alltt}
 
-
-
-
-
-
-
-
-
-
-
-
index 95f945ff51099f69a608b12e577dca8901837aeb..5f994af29f667beb4ec916e59e9f64954bfe9671 100644 (file)
@@ -1,6 +1,11 @@
 \subsection{Messages}
 
 \label{messages}
+Although \charmpp supports automated parameter marshalling for entry methods,
+you can also manually handle the process of packing and unpacking parameters by
+using messages. By using messages, you can potentially improve performance by
+avoiding unnecessary copying
+
 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.
index 8122bd8ff27a4f6742f1fcc9146d4dd769884bcf..10d3186344b5134bbc540a49184f10112f9747f2 100644 (file)
@@ -85,6 +85,7 @@ in \charmpp.  Instead, we refer to a remote chare via a ``proxy'',
 as explained below.
 
 \subsection{Proxies and Handles}
+\label{proxies}
 
 Those familiar with various component models (such as CORBA) in the
 distributed computing world will recognize ``proxy'' to be a dummy, standin