\section{Entry Methods}
\label{entry}

Member functions in the user program which function as entry methods have to be
defined in public scope within the class definition.
Entry methods typically do not return data and have a ``void'' return type.
An entry method with the same name as its enclosing class is a constructor entry method
and is used to create or spawn chare objects during execution.
Class member functions are annotated as entry methods by declaring them in the
the interface file as:
\begin{alltt}
entry void \uw{Entry1}(\uw{parameters});
\end{alltt}

\uw{Parameters} is either a list of serializable parameters, (e.g., ``int i,
double x''), or a message type (e.g., ``MyMessage *msg'').
Since parameters get marshalled into a message before being sent across the
network, in this manual we use ``message'' to mean either a message type or a
set of marshalled parameters.

%Constructors in \CC have no return type.
%Finally, sync methods, described below, may return a message.

Messages are lower level, more efficient, more flexible to use than parameter marshalling.

For example, a chare could have this entry method declaration in 
the interface ({\tt .ci}) file:
\begin{alltt}
  entry void foo(int i,int k);
\end{alltt}
Then invoking foo(2,3) on the chare proxy will eventually
invoke foo(2,3) on the chare object.

Since \charmpp\ runs on distributed memory machines, we cannot
pass an array via a pointer in the usual \CC\ way.  Instead,
we must specify the length of the array in the interface file, as:
\begin{alltt}
  entry void bar(int n,double arr[n]);
\end{alltt}
Since \CC\ does not recognize this syntax, the array data
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
it will be freed.  
This means any modifications made locally after the call will not be 
seen by the remote chare; and the remote chare's modifications
will be lost after the remote method returns-- \charmpp\ always 
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.  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}
  entry void doLine(float data[n],int n);
  entry void doPlane(float data[n*n],int n);
  entry void doSpace(int n,int m,int o,float data[n*m*o]);
  entry void doGeneral(int nd,int dims[nd],float data[product(dims,nd)]);
\end{alltt}
The array length expression between the square brackets can be 
any valid C++ expression, including a fixed constant, and may depend 
in any manner on any of the passed
parameters or even on global functions 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}

The marshalling system uses the pup framework to copy data,
meaning every user class that is marshalled needs either a
pup routine, a ``PUPbytes'' declaration, or a working operator|.
See the PUP description in Section~\ref{sec:pup} for more details 
on these routines.

Any user-defined types in the argument list must be declared 
before including the ``.decl.h'' file.
As usual in \CC, it is often dramatically more efficient to pass
a large structure by reference than by value.

