inserting new section about Python scripting.
[charm.git] / doc / charm++ / entry.tex
1 \subsection{Entry Methods}
2 \label{entry}
3
4 In \charmpp, \index{chare}chares, \index{group}groups and \index{nodegroup}
5 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.
6
7 An entry method is always a part of a chare--
8 there are no global entry methods in \charmpp{}.
9 Entry methods are declared in the the interface file as:
10
11 \begin{alltt}
12 entry void \uw{Entry1}(\uw{parameters});
13 \end{alltt}
14
15 \uw{Parameters} is either a list of marshalled parameters,
16 (e.g., ``int i, double x''), or a message description (e.g.,
17 ``MyMessage *msg'').  See section~\ref{marshalling} and
18 section~\ref{messages} for details on these types of
19 parameters.
20
21 Entry methods typically do not return data-- in \CC, they have
22 return type ``void''.  An entry method with the same name
23 as its enclosing class is a constructor.  Constructors in \CC
24 have no return type.  Finally, sync methods, described below,
25 may return a message.
26
27 \subsubsection{Entry Method Attributes}
28 \label{attributes}
29
30 \charmpp{}  provides a handful of special attributes that \index{entry
31 method}entry methods may have.  In order to give a particular \index{entry
32 method}entry method an attribute, you must specify the keyword for the desired
33 attribute in the attribute list of that entry method's {\tt .ci} file
34 declaration.  The syntax for this is as follows:
35
36 \begin{alltt}
37 entry [\uw{attribute1}, ..., \uw{attributeN}] void \uw{EntryMethod}(\uw{parameters});
38 \end{alltt}
39
40 \charmpp{} currently offers the following attributes that one may give an 
41 entry method:
42 \kw{threaded}, \kw{sync}, \kw{exclusive}, \kw{nokeep}, \kw{notrace}, \kw{immediate}, \kw{expedited}.
43
44 \begin{description}
45 \index{threaded}\item[Threaded] \index{entry method}entry methods are simply entry
46 methods which are run in their own nonpremptible threads.  To make an
47 \index{entry method}entry method threaded, one simply adds the keyword
48 \kw{threaded} to the attribute list of that entry method.
49
50 \index{sync}\item[Sync] \index{entry method}entry methods are special in that calls to
51 sync entry methods are blocking - they do not return control to the caller
52 until the method is finished executing completely.  Sync methods may have
53 return values; however, they may only return messages.  To make an \index{entry
54 method}entry method a sync entry method, add the keyword \kw{sync} to the
55 attribute list of that entry method.
56
57 \index{exclusive}\item[Exclusive] entry methods, which exist only on node groups, are
58 \index{entry method}entry methods that do not execute while other exclusive
59 \index{entry method}entry methods of its node group are executing in the same
60 node.  If one exclusive method of a node group is executing on node 0, and
61 another one is scheduled to run on that same node, the second exclusive method
62 will wait for the first to finish before it executes.  To make an \index{entry
63 method}entry method exclusive, add the keyword \kw{exclusive} to that
64 entry method's attribute list.
65
66 \index{nokeep}\item[Nokeep] entry methods tells Charm++ that messages passed to
67 these user entry methods will not be kept by the calls. Charm++ runtime
68 may be able to adopt optimization for reusing the message memory.
69
70 \index{notrace}\item[Notrace] entry methods simply tells Charm++ that calls to 
71 these entry methods should be not traced in trace projections or summary mode.
72
73 \index{immediate}\item[Immediate] entry methods are entry functions in which 
74 short messages can be executed in an ``immediate'' fashion when they are
75 received either by an interrupt (Network version) or by a communication thread
76 (in SMP version). Such messages can be useful for implementing
77 multicasts/reductions as well as data lookup, in which case processing of
78 critical messages won't be delayed (in the scheduler queue) by entry functions
79 that could take long time to finish. Immediate messages are only available for
80 nodegroup entry methods. Immediate messages are implicitly ``exclusive'' on each
81 node, that is one execution of immediate message will not be interrupted by
82 another. Function \kw{CmiProbeImmediateMsg()} can be called in users code to
83 probe and process immediate messages periodically.
84
85 \index{expedited}\item[Expedited] entry methods are entry functions 
86 that skip Charm++'s priority-based message queue. It is useful for messages that
87 require prompt processing however in the situation when immediate message does
88 not apply. Compared with immediate message, it provides a more general solution
89 that works for all Charm++ objects, i.e. Chare, Group, NodeGroup and Chare
90 Array. However, skipscheduler message still needs to be scheduled in low level
91 Converse message queue and be processed in the order of arrival. It may still
92 suffer from long running entry methods.
93
94
95 \index{python}\item[Python] entry methods are methods which are enabled to be
96 called from python scripts running as explained in section~\ref{python}. In
97 order to work, the object owning the method must also be declared with the
98 keywork \kw{python}.
99
100 \end{description}