\section{Entry Method Attributes}

\label{attributes}

\charmpp{}  provides a handful of special attributes that \index{entry
method}entry methods may have.  In order to give a particular \index{entry
method}entry method an attribute, you must specify the keyword for the desired
attribute in the attribute list of that entry method's {\tt .ci} file
declaration.  The syntax for this is as follows:

\begin{alltt}
entry [\uw{attribute1}, ..., \uw{attributeN}] void \uw{EntryMethod}(\uw{parameters});
\end{alltt}

\charmpp{} currently offers the following attributes that one may assign to 
an entry method:
\kw{threaded}, \kw{sync}, \kw{exclusive}, \kw{nokeep}, \kw{notrace}, \kw{appwork}, \kw{immediate}, \kw{expedited}, \kw{inline}, \kw{local}, \kw{python}.

\begin{description}
\index{threaded}\item[threaded] \index{entry method}entry methods 
run in their own non-preemptible threads. These
entry methods may perform blocking operations, such as calls to a
\kw{sync} entry method, or explicitly suspending themselves. For more
details, refer to section~\ref{threaded}.

\index{sync}\item[sync] \index{entry method}entry methods are special in that
calls to them are blocking--they do not return control to the caller until the
method finishes execution completely. Sync methods may have return values;
however, they may only return messages. Callers must run in a thread separate
from the runtime scheduler, e.g. a \kw{threaded} entry methods.  Calls
expecting a return value will receive it as the return from the proxy
invocation:
\begin{alltt}
 ReturnMsg* m;
 m = A[i].foo(a, b, c);
\end{alltt}
For more details, refer to section~\ref{sync}.

\index{exclusive}\item[exclusive] \index{entry method} entry methods should
only exist on NodeGroup objects. One such entry method will not execute while
some other exclusive entry methods belonging to the same NodeGroup object are
executing on the same node. In other words, if one exclusive method of a
NodeGroup object is executing on node N, and another one is scheduled to run on
the same node, the second exclusive method will wait to execute until the first
one finishes. An example can be found in \testrefdir{pingpong}.

\index{nokeep}\item[nokeep] entry methods only take a message as the argument,
and the memory buffer for this message will be managed by the \charmpp{}
runtime rather than the user calls. This means that user has to guarantee that
the message should not be buffered for a later usage or be freed in the user 
codes. Otherwise, a runtime error will be caused. 
Such entry methods entail runtime 
optimizations such as reusing the message memory. An example can be found in
\examplerefdir{histogram\_group}.
%these user entry methods will not be kept by the calls. Charm++ runtime
%may be able to adopt optimization for reusing the message memory.

\index{notrace}\item[notrace] entry methods will not be traced during execution. As a result, they will not be considered and displayed in Projections for
performance analysis.

\index{appwork}\item[appwork] this entry method will be marked as executing application work. It will be used for performance analysis.

\index{immediate}\item[immediate] entry methods are executed in an
``immediate'' fashion as they skip the message scheduling while other normal
entry methods donot. Immediate entry methods should be only associcated with
NodeGroup objects although it is not checked during compilation. If the
destination of such entry method is on the local node, then the method will be
executed in the context of the regular PE regardless the execution mode of
\charmpp{} runtime. However, in the SMP mode, if the destination of the method
is on the remote node, then the method will be executed in the context of the
communication thread.  
%are entry functions in which 
%short messages can be executed in an ``immediate'' fashion when they are
%received either by an interrupt (Network version) or by a communication thread
%(in SMP version). 
Such entry methods can be useful for implementing multicasts/reductions as well
as data lookup when such operations are on the performance critical path. On a
certain \charmpp{} PE, skipping the normal message scheduling prevents the
execution of immediate entry methods from being delayed by entry functions that
could take a long time to finish. Immediate entry methods are implicitly
``exclusive'' on each node, meaning that one execution of immediate message
will not be interrupted by another. Function \kw{CmiProbeImmediateMsg()} can be
called in user codes to probe and process immediate messages periodically. An
example ``immediatering'' can be found in \testrefdir{megatest}.

\index{expedited}\item[expedited] entry methods skip the priority-based message
queue in \charmpp{} runtime. It is useful for messages that require prompt
processing when adding the immediate attribute to the message does not apply.
Compared with the immediate attribute, the expedited attribute provides a more
general solution that works for all types of \charmpp{} objects, i.e. Chare,
Group, NodeGroup and Chare Array. However, expedited entry methods will still
be scheduled in the lower-level Converse message queue, and be processed in the
order of message arrival. Therefore, they may still suffer from delays caused
by long running entry methods. An example can be found in 
\examplerefdir{satisfiability}.

\index{inline}\item[inline] entry methods will be immediately invoked if the
message recipient happens to be on the same PE. These entry methods need to be
re-entrant as they could be called multiple times recursively. If the recipient
resides on a non-local PE, a regular message is sent, and \kw{inline} has no
effect. An example ``inlineem'' can be found in \testrefdir{megatest}.

\index{local}\item[local] entry methods are equivalent to normal function
calls: the entry method is always executed immediately. This feature is
available only for Group objects and Chare Array objects. The user has to
guarantee that the recipient chare element reside on the same PE. Otherwise,
the application will abort on a failure. If the \kw{local} entry method uses
parameter marshalling, instead of marshalling input parameters into a message,
it will pass them direcly to the callee. This implies that the callee can
modify the caller data if method parameters are passed by pointer or reference.
Furthermore, input parameters do not require to be PUPable. Considering that
these entry methods always execute immediately, they are allowed to have a
non-void return value. Nevertheless, the return type of the method must be a
pointer. An example can be found in \examplerefdir{hello/local}.

\index{python}\item[python] entry methods are enabled to be
called from python scripts as explained in chapter~\ref{python}. Note that the object owning the method must also be declared with the
keyword \kw{python}. Refer to chapter~\ref{python} for more details.

\index{reductiontarget}\item[reductiontarget] entry methods may be used as the
target of reductions, despite not taking CkReductionMsg as an argument.
See section~\ref{reductions} for more references.

\end{description}
