doc/charm++/marshalling.tex

   1 \section{Entry Methods}
   2 \label{entry}
   3
   4 Member functions in the user program which function as entry methods have to be
   5 defined in public scope within the class definition.
   6 Entry methods typically do not return data and have a ``void'' return type.
   7 An entry method with the same name as its enclosing class is a constructor entry method
   8 and is used to create or spawn chare objects during execution.
   9 Class member functions are annotated as entry methods by declaring them in
  10 the interface file as:
  11 \begin{alltt}
  12 entry void \uw{Entry1}(\uw{parameters});
  13 \end{alltt}
  14
  15 \uw{Parameters} is either a list of serializable parameters, (e.g., ``int i,
  16 double x''), or a message type (e.g., ``MyMessage *msg'').
  17 Since parameters get marshalled into a message before being sent across the
  18 network, in this manual we use ``message'' to mean either a message type or a
  19 set of marshalled parameters.
  20
  21 %Constructors in \CC have no return type.
  22 %Finally, sync methods, described below, may return a message.
  23
  24 Messages are lower level, more efficient, more flexible to use than parameter marshalling.
  25
  26 For example, a chare could have this entry method declaration in
  27 the interface ({\tt .ci}) file:
  28 \begin{alltt}
  29   entry void foo(int i,int k);
  30 \end{alltt}
  31 Then invoking foo(2,3) on the chare proxy will eventually
  32 invoke foo(2,3) on the chare object.
  33
  34 Since \charmpp\ runs on distributed memory machines, we cannot
  35 pass an array via a pointer in the usual \CC\ way.  Instead,
  36 we must specify the length of the array in the interface file, as:
  37 \begin{alltt}
  38   entry void bar(int n,double arr[n]);
  39 \end{alltt}
  40 Since \CC\ does not recognize this syntax, the array data
  41 must be passed to the chare proxy as a simple pointer.
  42 The array data will be copied and sent to the
  43 destination processor, where the chare will receive the copy
  44 via a simple pointer again.  The remote copy of the data
  45 will be kept until the remote method returns, when
  46 it will be freed.
  47 This means any modifications made locally after the call will not be
  48 seen by the remote chare; and the remote chare's modifications
  49 will be lost after the remote method returns-- \charmpp\ always
  50 uses call-by-value, even for arrays and structures.
  51
  52 This also means the data must be copied on the sending
  53 side, and to be kept must be copied again
  54 at the receive side.  Especially for large arrays, this
  55 is less efficient than messages, as described in the next section.
  56
  57 Array parameters and other parameters can be combined in arbitrary ways, as:
  58 \begin{alltt}
  59   entry void doLine(float data[n],int n);
  60   entry void doPlane(float data[n*n],int n);
  61   entry void doSpace(int n,int m,int o,float data[n*m*o]);
  62   entry void doGeneral(int nd,int dims[nd],float data[product(dims,nd)]);
  63 \end{alltt}
  64 The array length expression between the square brackets can be
  65 any valid C++ expression, including a fixed constant, and may depend
  66 in any manner on any of the passed
  67 parameters or even on global functions or global data.  The array length
  68 expression is evaluated exactly once per invocation, on the sending side only.
  69 Thus executing the \kw{doGeneral} method above will invoke the
  70 (user-defined) \kw{product} function exactly once on the sending
  71 processor.
  72
  73 \subsubsection{Marshalling User-Defined Structures and Classes}
  74
  75 The marshalling system uses the pup framework to copy data,
  76 meaning every user class that is marshalled needs either a
  77 pup routine, a ``PUPbytes'' declaration, or a working operator|.
  78 See the PUP description in Section~\ref{sec:pup} for more details
  79 on these routines.
  80
  81 Any user-defined types in the argument list must be declared
  82 before including the ``.decl.h'' file.
  83 Any user-defined types must be fully defined before the entry
  84 method declaration that consumes it.  This is typically done by
  85 including the header defining the type in the {\tt .ci} file.
  86 Alternatively, one may define it before including the
  87 {\tt .decl.h} file.  As usual in \CC, it is often dramatically
  88  more efficient to pass a large structure by reference than by value.
  89
  90 As an example, refer to the following code from \examplerefdir{PUP/HeapPUP}:
  91
  92 \begin{alltt}
  93 // In HeapObject.h:
  94
  95 class HeapObject \{
  96  public:
  97   int publicInt;
  98
  99   // ... other methods ...
 100
 101   void pup(PUP::er &p) \{
 102     // remember to pup your superclass if there is one
 103     p|publicInt;
 104     p|privateBool;
 105     if (p.isUnpacking())
 106       data = new float[publicInt];
 107     PUParray(p, data, publicInt);
 108   \}
 109
 110  private:
 111   bool privateBool;
 112   float *data;
 113 \};
 114
 115 // In SimplePup.ci:
 116
 117 mainmodule SimplePUP \{
 118   include "HeapObject.h";
 119
 120   // ... other Chare declarations ...
 121
 122   array [1D] SimpleArray\{
 123     entry SimpleArray();
 124     entry void acceptData(HeapObject &inData);
 125   \};
 126 \};
 127
 128 // In SimplePup.h:
 129
 130 #include "SimplePUP.decl.h"
 131
 132 // ... other definitions ...
 133
 134 class SimpleArray : public CBase\_SimpleArray \{
 135  public:
 136   void acceptData(HeapObject &inData) \{
 137     // ... code using marshalled parameter ...
 138   \}
 139 \};
 140
 141 // In SimplePup.C:
 142
 143 #include "SimplePUP.h"
 144
 145 main::main(CkArgMsg *m)
 146 \{
 147   // normal object construction
 148   HeapObject exampleObject(... parameters ...);
 149
 150   // normal chare array construction
 151   CProxy\_SimpleArray simpleProxy = CProxy\_SimpleArray::ckNew(30);
 152
 153   // pass object to remote method invocation on the chare array
 154   simpleProxy[29].acceptData(exampleObject);
 155 \}
 156
 157 #include "SimplePUP.def.h"
 158 \end{alltt}