f78caefe148ec73947471133f213377081137561
[charm.git] / doc / charm++ / entry.tex
1 \section{Entry Method Attributes}
2
3 \label{attributes}
4
5 \charmpp{}  provides a handful of special attributes that \index{entry
6 method}entry methods may have.  In order to give a particular \index{entry
7 method}entry method an attribute, you must specify the keyword for the desired
8 attribute in the attribute list of that entry method's {\tt .ci} file
9 declaration.  The syntax for this is as follows:
10
11 \begin{alltt}
12 entry [\uw{attribute1}, ..., \uw{attributeN}] void \uw{EntryMethod}(\uw{parameters});
13 \end{alltt}
14
15 \charmpp{} currently offers the following attributes that one may assign to 
16 an entry method:
17 \kw{threaded}, \kw{sync}, \kw{exclusive}, \kw{nokeep}, \kw{notrace}, \kw{immediate}, \kw{expedited}, \kw{inline}, \kw{local}, \kw{python}.
18
19 \begin{description}
20 \index{threaded}\item[threaded] \index{entry method}entry methods 
21 run in their own non-preemptible threads. These
22 entry methods may perform blocking operations, such as calls to a
23 \kw{sync} entry method, or explicitly suspending themselves.
24
25 \index{sync}\item[sync] \index{entry method}entry methods are special in that
26 calls to them are blocking--they do not return control to the caller until the
27 method finishes execution completely. Sync methods may have return values;
28 however, they may only return messages. Callers must run in a thread separate
29 from the runtime scheduler, e.g. a \kw{threaded} entry methods.  Calls
30 expecting a return value will receive it as the return from the proxy
31 invocation:
32 \begin{alltt}
33 ReturnMsg* m;
34 m = A[i].foo(a, b, c);
35 \end{alltt}
36
37 \index{exclusive}\item[exclusive] \index{entry method} entry methods should
38 only exist on NodeGroup objects. One such entry method will not execute while
39 some other exclusive entry methods belonging to the same NodeGroup object are
40 executing on the same node. In other words, if one exclusive method of a
41 NodeGroup object is executing on node N, and another one is scheduled to run on
42 the same node, the second exclusive method will wait to execute until the first
43 one finishes.
44
45 \index{nokeep}\item[nokeep] entry methods only take a message as the argument,
46 and the memory buffer for this message will be managed by the \charmpp{}
47 runtime rather than the user calls. This means that user has to guarantee that
48 the message should not be buffered for a later usage or be freed in the user 
49 codes. Otherwise, a runtime error will be caused. 
50 Such entry methods entail runtime 
51 optimizations such as reusing the message memory.
52 %these user entry methods will not be kept by the calls. Charm++ runtime
53 %may be able to adopt optimization for reusing the message memory.
54
55 \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
56 performance analysis.
57
58 \index{immediate}\item[immediate] entry methods are executed in an
59 ``immediate'' fashion as they skip the message scheduling while other normal
60 entry methods donot. Immediate entry methods should be only associcated with
61 NodeGroup objects although it is not checked during compilation. If the
62 destination of such entry method is on the local node, then the method will be
63 executed in the context of the regular PE regardless the execution mode of
64 \charmpp{} runtime. However, in the SMP mode, if the destination of the method
65 is on the remote node, then the method will be executed in the context of the
66 communication thread.  
67 %are entry functions in which 
68 %short messages can be executed in an ``immediate'' fashion when they are
69 %received either by an interrupt (Network version) or by a communication thread
70 %(in SMP version). 
71 Such entry methods can be useful for implementing multicasts/reductions as well
72 as data lookup when such operations are on the performance critical path. On a
73 certain \charmpp{} PE, skipping the normal message scheduling prevents the
74 execution of immediate entry methods from being delayed by entry functions that
75 could take a long time to finish. Immediate entry methods are implicitly
76 ``exclusive'' on each node, meaning that one execution of immediate message
77 will not be interrupted by another. Function \kw{CmiProbeImmediateMsg()} can be
78 called in user codes to probe and process immediate messages periodically.
79
80 \index{expedited}\item[expedited] entry methods skip the priority-based message
81 queue in \charmpp{} runtime. It is useful for messages that require prompt
82 processing when adding the immediate attribute to the message does not apply.
83 Compared with the immediate attribute, the expedited attribute provides a more
84 general solution that works for all types of \charmpp{} objects, i.e. Chare,
85 Group, NodeGroup and Chare Array. However, expedited entry methods will still
86 be scheduled in the lower-level Converse message queue, and be processed in the
87 order of message arrival. Therefore, they may still suffer from delays caused
88 by long running entry methods.
89
90 \index{inline}\item[inline] entry methods will be immediately invoked if the
91 message recipient happens to be on the same PE. These entry methods need to be
92 re-entrant as they could be called multiple times recursively. If the recipient
93 resides on a non-local PE, a regular message is sent, and \kw{inline} has no
94 effect.
95
96 \index{local}\item[local] entry methods are equivalent to normal function
97 calls: the entry method is always executed immediately. This feature is
98 available only for Group objects and Chare Array objects. The user has to
99 guarantee that the recipient chare element reside on the same PE. Otherwise,
100 the application will abort on a failure. If the \kw{local} entry method uses
101 parameter marshalling, instead of marshalling input parameters into a message,
102 it will pass them direcly to the callee. This implies that the callee can
103 modify the caller data if method parameters are passed by pointer or reference.
104 Furthermore, input parameters do not require to be PUPable. Considering that
105 these entry methods always execute immediately, they are allowed to have a
106 non-void return value. Nevertheless, the return type of the method must be a
107 pointer.
108
109 \index{python}\item[python] entry methods are enabled to be
110 called from python scripts as explained in chapter~\ref{python}. Note that the object owning the method must also be declared with the
111 keyword \kw{python}.
112
113 \index{reductiontarget}\item[reductiontarget] entry methods may be used as the
114 target of reductions, despite not taking CkReductionMsg as an argument.
115 See section~\ref{reductions} for more references.
116
117 \end{description}