1 \section{Entry Methods
}
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:
12 entry void
\uw{Entry1
}(
\uw{parameters
});
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.
21 %Constructors in \CC have no return type.
22 %Finally, sync methods, described below, may return a message.
24 Messages are lower level, more efficient, more flexible to use than parameter marshalling.
26 For example, a chare could have this entry method declaration in
27 the interface (
{\tt .ci
}) file:
29 entry void foo(int i,int k);
31 Then invoking foo(
2,
3) on the chare proxy will eventually
32 invoke foo(
2,
3) on the chare object.
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:
38 entry void bar(int n,double arr
[n
]);
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
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.
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.
57 Array parameters and other parameters can be combined in arbitrary ways, as:
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)
]);
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
73 \subsubsection{Marshalling User-Defined Structures and Classes
}
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
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.
90 As an example, refer to the following code from
\examplerefdir{PUP/HeapPUP
}:
99 // ... other methods ...
101 void pup(PUP::er &p) \
{
102 // remember to pup your superclass if there is one
106 data = new float
[publicInt
];
107 PUParray(p, data, publicInt);
117 mainmodule SimplePUP \
{
118 include "HeapObject.h";
120 // ... other Chare declarations ...
122 array
[1D
] SimpleArray\
{
124 entry void acceptData(HeapObject &inData);
130 #include "SimplePUP.decl.h"
132 // ... other definitions ...
134 class SimpleArray : public CBase
\_SimpleArray \
{
136 void acceptData(HeapObject &inData) \
{
137 // ... code using marshalled parameter ...
143 #include "SimplePUP.h"
145 main::main(CkArgMsg *m)
147 // normal object construction
148 HeapObject exampleObject(... parameters ...);
150 // normal chare array construction
151 CProxy
\_SimpleArray simpleProxy = CProxy
\_SimpleArray::ckNew(
30);
153 // pass object to remote method invocation on the chare array
154 simpleProxy
[29].acceptData(exampleObject);
157 #include "SimplePUP.def.h"