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},
  18 \kw{appwork}, \kw{immediate}, \kw{expedited}, \kw{inline}, \kw{local},
  19 \kw{python}, \kw{reductiontarget}, \kw{aggregate}.
  20
  21 \begin{description}
  22 \index{threaded}\item[threaded] \index{entry method}entry methods
  23 run in their own non-preemptible threads. These
  24 entry methods may perform blocking operations, such as calls to a
  25 \kw{sync} entry method, or explicitly suspending themselves. For more
  26 details, refer to section~\ref{threaded}.
  27
  28 \index{sync}\item[sync] \index{entry method}entry methods are special in that
  29 calls to them are blocking--they do not return control to the caller until the
  30 method finishes execution completely. Sync methods may have return values;
  31 however, they may only return messages or data types that have the PUP method implemented. Callers must run in a thread separate
  32 from the runtime scheduler, e.g. a \kw{threaded} entry methods.  Calls
  33 expecting a return value will receive it as the return from the proxy
  34 invocation:
  35 \begin{alltt}
  36  ReturnMsg* m;
  37  m = A[i].foo(a, b, c);
  38 \end{alltt}
  39 For more details, refer to section~\ref{sync}.
  40
  41 \index{exclusive}\item[exclusive] \index{entry method} entry methods should
  42 only exist on NodeGroup objects. One such entry method will not execute while
  43 some other exclusive entry methods belonging to the same NodeGroup object are
  44 executing on the same node. In other words, if one exclusive method of a
  45 NodeGroup object is executing on node N, and another one is scheduled to run on
  46 the same node, the second exclusive method will wait to execute until the first
  47 one finishes. An example can be found in \testrefdir{pingpong}.
  48
  49 \index{nokeep}\item[nokeep] entry methods take only a message as their lone argument,
  50 and the memory buffer for this message is managed by the \charmpp{} runtime system
  51 rather than by the user. This means that the user has to guarantee that
  52 the message will not be buffered for later usage or be freed in the user
  53 code. Additionally, users are not allowed to modify the contents of a nokeep
  54 message, since for a broadcast the same message can be reused for all entry method
  55 invocations on each PE. If a user frees the message or modifies its contents,
  56 a runtime error may result. An example can be found in \examplerefdir{histogram\_group}.
  57
  58 \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
  59   performance analysis. Additionally, \texttt{immediate} entry methods are by default \texttt{notrace} and will
  60 not be traced during execution.
  61
  62 \index{appwork}\item[appwork] this entry method will be marked as executing application work. It will be used for performance analysis.
  63
  64 \index{immediate}\item[immediate] entry methods are executed in an
  65 ``immediate'' fashion as they skip the message scheduling while other normal
  66 entry methods do not. Immediate entry methods can only be associated with
  67 NodeGroup objects, otherwise a compilation error will result. If the
  68 destination of such entry method is on the local node, then the method will be
  69 executed in the context of the regular PE regardless the execution mode of
  70 \charmpp{} runtime. However, in the SMP mode, if the destination of the method
  71 is on the remote node, then the method will be executed in the context of the
  72 communication thread. For that reason, immediate entry methods should be used
  73 for code that is performance critical and does not take too long in terms of
  74 execution time because long running entry methods can delay communication by
  75 occupying the communication thread for entry method execution rather than
  76 remote communication.
  77
  78 %are entry functions in which
  79 %short messages can be executed in an ``immediate'' fashion when they are
  80 %received either by an interrupt (Network version) or by a communication thread
  81 %(in SMP version).
  82 Such entry methods can be useful for implementing multicasts/reductions as well
  83 as data lookup when such operations are on the performance critical path. On a
  84 certain \charmpp{} PE, skipping the normal message scheduling prevents the
  85 execution of immediate entry methods from being delayed by entry functions that
  86 could take a long time to finish. Immediate entry methods are implicitly
  87 ``exclusive'' on each node, meaning that one execution of immediate message
  88 will not be interrupted by another. Function \kw{CmiProbeImmediateMsg()} can be
  89 called in user codes to probe and process immediate messages periodically. Also
  90 note that \texttt{immediate} entry methods are by default \texttt{notrace} and are
  91 not traced during execution. An example of \texttt{immediate} entry method
  92 can be found in \examplerefdir{immediateEntryMethod}.
  93
  94 \index{expedited}\item[expedited] entry methods skip the priority-based message
  95 queue in \charmpp{} runtime. It is useful for messages that require prompt
  96 processing when adding the immediate attribute to the message does not apply.
  97 Compared with the immediate attribute, the expedited attribute provides a more
  98 general solution that works for all types of \charmpp{} objects, i.e. Chare,
  99 Group, NodeGroup and Chare Array. However, expedited entry methods will still
 100 be scheduled in the lower-level Converse message queue, and be processed in the
 101 order of message arrival. Therefore, they may still suffer from delays caused
 102 by long running entry methods. An example can be found in
 103 \examplerefdir{satisfiability}.
 104
 105 \index{inline}\item[inline] entry methods will be called as a normal C++ member function
 106 if the message recipient happens to be on the same PE. The call to the function
 107 will happen inline, and control will return to the calling function after the
 108 inline method completes. Because of this, these entry methods need to be
 109 re-entrant as they could be called multiple times recursively. Parameters to the
 110 inline method will be passed by reference to avoid any copying, packing,
 111 or unpacking of the parameters. This makes inline calls effective when large
 112 amounts of data are being passed, and copying or packing the data would be an
 113 expensive operation.
 114 Perfect forwarding has been implemented to allow for seamless passing of both
 115 lvalue and rvalue references. Note that calls with rvalue references must take
 116 place in the same translation unit as the .decl.h file to allow for the
 117 appropriate template instantiations. Alternatively, the method can be made
 118 templated and referenced from multiple translation units via \texttt{CK\_TEMPLATES\_ONLY}.
 119 An explicit instantiation of all lvalue references is provided for
 120 compatibility with existing code.
 121 If the recipient resides on a different PE, a regular
 122 message is sent with the message arguments packed up using PUP, and \kw{inline}
 123 has no effect. An example ``inlineem'' can be found in \testrefdir{megatest}.
 124
 125 \index{local}\item[local] entry methods are equivalent to normal function
 126 calls: the entry method is always executed immediately. This feature is
 127 available only for Group objects and Chare Array objects. The user has to
 128 guarantee that the recipient chare element resides on the same PE. Otherwise,
 129 the application will abort with a failure. If the \kw{local} entry method uses
 130 parameter marshalling, instead of marshalling input parameters into a message,
 131 it will pass them directly to the callee. This implies that the callee can
 132 modify the caller data if method parameters are passed by pointer or reference.
 133 The above description of perfect forwarding for inline entry methods also
 134 applies to local entry methods.
 135 Furthermore, input parameters are not required to be PUPable. Considering that
 136 these entry methods always execute immediately, they are allowed to have a
 137 non-void return value. An example can be found in \examplerefdir{hello/local}.
 138
 139 \index{python}\item[python] entry methods are enabled to be
 140 called from python scripts as explained in chapter~\ref{python}. Note that the object owning the method must also be declared with the
 141 keyword \kw{python}. Refer to chapter~\ref{python} for more details.
 142
 143 \index{reductiontarget}\item[reductiontarget] entry methods can be
 144 used as the target of reductions while taking arguments of the same
 145 type specified in the contribute call rather than a message of type
 146 \kw{CkReductionMsg}. See section~\ref{reductions} for more
 147 information.
 148
 149 \index{aggregate}\item[aggregate] data sent to this entry method will be
 150 aggregated into larger messages before being sent, to reduce fine-grained
 151 overhead. The aggregation is handled by the Topological Routing and Aggregation
 152 Module (TRAM). The argument to this entry method must be a single fixed-size
 153 object. More details on TRAM are given in the
 154 \href{http://charm.cs.illinois.edu/manuals/html/libraries/manual-1p.html#TRAM}
 155 {TRAM section} of the libraries manual.
 156
 157 \end{description}