Docs: remove pointless, redundant verbiage
[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.
64
65 \index{nokeep}\item[nokeep] entry methods tells Charm++ that messages passed to
66 these user entry methods will not be kept by the calls. Charm++ runtime
67 may be able to adopt optimization for reusing the message memory.
68
69 \index{notrace}\item[notrace] entry methods simply tells Charm++ that calls to 
70 these entry methods should be not traced in trace projections or summary mode.
71
72 \index{immediate}\item[immediate] entry methods are entry functions in which 
73 short messages can be executed in an ``immediate'' fashion when they are
74 received either by an interrupt (Network version) or by a communication thread
75 (in SMP version). Such messages can be useful for implementing
76 multicasts/reductions as well as data lookup, in which case processing of
77 critical messages won't be delayed (in the scheduler queue) by entry functions
78 that could take long time to finish. Immediate messages are only available for
79 nodegroup entry methods. Immediate messages are implicitly ``exclusive'' on each
80 node, that is one execution of immediate message will not be interrupted by
81 another. Function \kw{CmiProbeImmediateMsg()} can be called in users code to
82 probe and process immediate messages periodically.
83
84 \index{expedited}\item[expedited] entry methods are entry functions 
85 that skip Charm++'s priority-based message queue. It is useful for messages that
86 require prompt processing however in the situation when immediate message does
87 not apply. Compared with immediate message, it provides a more general solution
88 that works for all Charm++ objects, i.e. Chare, Group, NodeGroup and Chare
89 Array. However, expedited message still needs to be scheduled in low level
90 Converse message queue and be processed in the order of arrival. It may still
91 suffer from long running entry methods.
92
93 \index{inline}\item[inline] entry methods are entry functions in which the
94 message is delivered immediately to the recipient if it happens to reside on the
95 same processor. Therefore, these entry methods need to be reentrant, as they
96 could be called multiple times recursively. If the recipient reside on another
97 processor, a regular message is sent, and \kw{inline} has no effect.
98
99 \index{local}\item[local] entry methods are equivalent to function calls: the
100 entry method is always called immediately. This feature is available only for
101 Groups and Chare Arrays. The user has to guarantee that the recipient chare
102 element reside on the same processor, a failure will result in the application
103 to abort. In contrast will all other entry methods where input parameters are
104 marshalled into a message, \kw{local} entry methods pass them direcly to the
105 callee. This implies that the callee can modify the caller data if this is
106 passed by pointer or reference. Furthermore, the input parameters do not require
107 to be PUPable. Being these entry methods always called immediately, they are
108 allowed to have a non-void return type. Nevertheless, the returned type must be
109 a pointer.
110
111 \index{python}\item[python] entry methods are methods which are enabled to be
112 called from python scripts running as explained in section~\ref{python}. In
113 order to work, the object owning the method must also be declared with the
114 keyword \kw{python}.
115
116 \end{description}