0bdd22f90dc6b5b08aff771350cc4864404bcfbb
[charm.git] / doc / charm++ / entry.tex
1 \subsection{Entry Methods}
2
3 \label{entry}
4
5 In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
6 nodegroups communicate using remote method invocation.  These ``remote entry'' methods may either take marshalled parameters, described in the next section; or special objects called messages.  Messages are lower level, more efficient, more flexible, and more difficult to use than parameter marshalling.
7
8 An entry method is always a part of a chare--
9 there are no global entry methods in \charmpp{}.
10 Entry methods are declared in the the interface file as:
11
12 \begin{alltt}
13 entry void \uw{Entry1}(\uw{parameters});
14 \end{alltt}
15
16 \uw{Parameters} is either a list of marshalled parameters,
17 (e.g., ``int i, double x''), or a message description (e.g.,
18 ``MyMessage *msg'').  See section~\ref{marshalling} and
19 section~\ref{messages} for details on these types of
20 parameters.
21
22 Entry methods typically do not return data-- in \CC, they have
23 return type ``void''.  An entry method with the same name
24 as its enclosing class is a constructor.  Constructors in \CC
25 have no return type.  Finally, sync methods, described below,
26 may return a message.
27
28 \subsubsection{Entry Method Attributes}
29
30 \label{attributes}
31
32 \charmpp{}  provides a handful of special attributes that \index{entry
33 method}entry methods may have.  In order to give a particular \index{entry
34 method}entry method an attribute, you must specify the keyword for the desired
35 attribute in the attribute list of that entry method's {\tt .ci} file
36 declaration.  The syntax for this is as follows:
37
38 \begin{alltt}
39 entry [\uw{attribute1}, ..., \uw{attributeN}] void \uw{EntryMethod}(\uw{parameters});
40 \end{alltt}
41
42 \charmpp{} currently offers the following attributes that one may assign to 
43 an entry method:
44 \kw{threaded}, \kw{sync}, \kw{exclusive}, \kw{nokeep}, \kw{notrace}, \kw{immediate}, \kw{expedited}, \kw{inline}, \kw{local}, \kw{python}.
45
46 \begin{description}
47 \index{threaded}\item[threaded] \index{entry method}entry methods are
48 entry methods which are run in their own nonpreemptible threads. These
49 entry methods may perform blocking operations, such as calls to a
50 \kw{sync} entry method, or explicitly suspend themselves.
51
52 \index{sync}\item[sync] \index{entry method}entry methods are special in that calls to
53 sync entry methods are blocking - they do not return control to the caller
54 until the method is finished executing completely.  Sync methods may have
55 return values; however, they may only return messages. Callers must run in a
56 thread separate from the runtime scheduler, e.g. a \kw{threaded} entry methods.
57
58 \index{exclusive}\item[exclusive] entry methods, which exist only on node groups, are
59 \index{entry method}entry methods that do not execute while other exclusive
60 \index{entry method}entry methods of its node group are executing in the same
61 node.  If one exclusive method of a node group is executing on node 0, and
62 another one is scheduled to run on that same node, the second exclusive method
63 will wait for the first to finish before it executes.  To make an \index{entry
64 method}entry method exclusive, add the keyword \kw{exclusive} to that
65 entry method's attribute list.
66
67 \index{nokeep}\item[nokeep] entry methods tells Charm++ that messages passed to
68 these user entry methods will not be kept by the calls. Charm++ runtime
69 may be able to adopt optimization for reusing the message memory.
70
71 \index{notrace}\item[notrace] entry methods simply tells Charm++ that calls to 
72 these entry methods should be not traced in trace projections or summary mode.
73
74 \index{immediate}\item[immediate] entry methods are entry functions in which 
75 short messages can be executed in an ``immediate'' fashion when they are
76 received either by an interrupt (Network version) or by a communication thread
77 (in SMP version). Such messages can be useful for implementing
78 multicasts/reductions as well as data lookup, in which case processing of
79 critical messages won't be delayed (in the scheduler queue) by entry functions
80 that could take long time to finish. Immediate messages are only available for
81 nodegroup entry methods. Immediate messages are implicitly ``exclusive'' on each
82 node, that is one execution of immediate message will not be interrupted by
83 another. Function \kw{CmiProbeImmediateMsg()} can be called in users code to
84 probe and process immediate messages periodically.
85
86 \index{expedited}\item[expedited] entry methods are entry functions 
87 that skip Charm++'s priority-based message queue. It is useful for messages that
88 require prompt processing however in the situation when immediate message does
89 not apply. Compared with immediate message, it provides a more general solution
90 that works for all Charm++ objects, i.e. Chare, Group, NodeGroup and Chare
91 Array. However, expedited message still needs to be scheduled in low level
92 Converse message queue and be processed in the order of arrival. It may still
93 suffer from long running entry methods.
94
95 \index{inline}\item[inline] entry methods are entry functions in which the
96 message is delivered immediately to the recipient if it happens to reside on the
97 same processor. Therefore, these entry methods need to be reentrant, as they
98 could be called multiple times recursively. If the recipient reside on another
99 processor, a regular message is sent, and \kw{inline} has no effect.
100
101 \index{local}\item[local] entry methods are equivalent to function calls: the
102 entry method is always called immediately. This feature is available only for
103 Groups and Chare Arrays. The user has to guarantee that the recipient chare
104 element reside on the same processor, a failure will result in the application
105 to abort. In contrast will all other entry methods where input parameters are
106 marshalled into a message, \kw{local} entry methods pass them direcly to the
107 callee. This implies that the callee can modify the caller data if this is
108 passed by pointer or reference. Furthermore, the input parameters do not require
109 to be PUPable. Being these entry methods always called immediately, they are
110 allowed to have a non-void return type. Nevertheless, the returned type must be
111 a pointer.
112
113 \index{python}\item[python] entry methods are methods which are enabled to be
114 called from python scripts running as explained in section~\ref{python}. In
115 order to work, the object owning the method must also be declared with the
116 keyword \kw{python}.
117
118 \end{description}