doc: promote section hierarchy appropriately
[charm.git] / 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 the
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 As usual in \CC, it is often dramatically more efficient to pass
84 a large structure by reference than by value.
85