doc/charm++/chares.tex

   1 \section{Chare Objects}
   2
   3 \index{chare}Chares are concurrent objects with methods that can be invoked
   4 remotely. These methods are known as \index{entry method}entry methods. All
   5 chares must have a constructor that is an entry method, and may have any
   6 number of other entry methods. All chare classes and their entry methods are
   7 declared in the interface (\texttt{.ci}) file:
   8
   9 \begin{alltt}
  10     chare ChareType
  11     \{
  12         entry ChareType(\uw{parameters1});
  13         entry void EntryMethodName(\uw{parameters2});
  14     \};
  15 \end{alltt}
  16
  17 Although it is {\em declared} in an interface file, a chare is a \CC{} object
  18 and must have a normal \CC{} {\em implementation} (definition) in addition. A
  19 chare class {\tt ChareType} must inherit from the class {\tt CBase\_ChareType},
  20 which is a special class that is generated by the \charmpp translator from the
  21 interface file. Note that \CC{} namespace constructs can be used in the
  22 interface file, as demonstrated in \examplerefdir{namespace}.
  23
  24 To be concrete, the \CC{} definition of the \index{chare}chare above might have
  25 the following definition in a \texttt{.h} file:
  26
  27 \begin{alltt}
  28    class ChareType : public CBase\_ChareType \{
  29        // Data and member functions as in C++
  30        public:
  31            ChareType(\uw{parameters1});
  32            void EntryMethodName2(\uw{parameters2});
  33    \};
  34 \end{alltt}
  35
  36 \index{chare}
  37 Each chare encapsulates data associated with medium-grained units of work in a
  38 parallel application.
  39 Chares can be dynamically created on any processor; there may
  40 be thousands of chares on a processor. The location of a chare is
  41 usually determined by the dynamic load balancing strategy. However,
  42 once a chare commences execution on a processor, it does not migrate
  43 to other processors\footnote{Except when it is part of an array.}.
  44 Chares do not have a default ``thread of
  45 control'': the entry methods \index{entry methods} in a
  46 chare execute in a message driven fashion upon the arrival of a
  47 message\footnote{Threaded methods augment this behavior since they execute in
  48 a separate user-level thread, and thus can block to wait for data.}.
  49
  50 The entry method definition specifies a function that is executed {\em without
  51 interruption} when a message is received and scheduled for processing. Only one
  52 message per chare is processed at a time.  Entry methods are defined exactly as
  53 normal \CC{} function members, except that they must have the return value
  54 \kw{void} (except for the constructor entry method which may not have a return
  55 value, and for a {\em synchronous} entry method, which is invoked by a {\em
  56 threaded} method in a remote chare). Each entry method can either take no
  57 arguments, take a list of arguments that the runtime system can automatically
  58 pack into a message and send (see section~\ref{entry}), or take a single
  59 argument that is a pointer to a \charmpp message (see section~\ref{messages}).
  60
  61 A chare's entry methods can be invoked via {\it proxies} (see
  62 section~\ref{proxies}). Proxies to a chare of type {\tt chareType} have type
  63 {\tt CProxy\_chareType}. By inheriting from the CBase parent class, each chare
  64 gets a {\tt thisProxy} member variable, which holds a proxy to itself. This
  65 proxy can be sent to other chares, allowing them to invoke entry methods on this
  66 chare.
  67
  68 \zap{
  69 Each chare instance is identified by a {\em handle} \index{handle}
  70 which is essentially a global pointer, and is unique across all
  71 processors.  The handle of a chare has type \kw{CkChareID}.  The
  72 variable \kw{thishandle} holds the handle of the
  73 chare whose entry function or public function is currently executing.
  74 \kw{thishandle} is a public instance variable of the chare object
  75 which is inherited from the system-defined superclass
  76 \kw{CBase}\_\uw{ClassType}.
  77 Following the older syntax, chares are also allowed to inherit directly
  78 for the superclass \kw{Chare} instead of \kw{CBase}\_\uw{ClassType}, although
  79 this form is not suggested.
  80 \kw{thishandle} can be used to set fields in a message. This
  81 mechanism allows chares to send their handles to other chares.
  82 }
  83
  84 \subsection{Chare Creation}
  85
  86 \label{chare creation}
  87
  88 Once you have declared and defined a chare class, you will want to create some
  89 chare objects to use. Chares are created by the {\tt ckNew} method, which is a
  90 static method of the chare's proxy class:
  91
  92 \begin{alltt}
  93    CProxy_chareType::ckNew(\uw{parameters}, int destPE);
  94 \end{alltt}
  95
  96 The {\tt parameters} correspond to the parameters of the chare's constructor.
  97 Even if the constructor takes several arguments, all of the arguments should be
  98 passed in order to {\tt ckNew}. If the constructor takes no arguments, the
  99 parameters are omitted. By default, the new chare's location is determined by
 100 the runtime system. However, this can be overridden by passing a value for
 101 {\tt destPE}, which specifies the PE where the chare will be created.
 102
 103 The \index{chare}chare creation method deposits the \index{seed}{\em seed} for
 104 a chare in a pool of seeds and returns immediately. The \index{chare}chare will
 105 be created later on some processor, as determined by the dynamic \index{load
 106 balancing}load balancing strategy (or by {\tt destPE}).
 107 When a \index{chare}chare is created, it is
 108 initialized by calling its \index{constructor}constructor \index{entry
 109 method}entry method with the parameters specified by {\tt ckNew}.
 110
 111 Suppose we have declared a chare class {\tt C} with a constructor that takes two
 112 arguments, an {\tt int} and a {\tt double}.
 113
 114 \begin{enumerate}
 115 \item{This will create a new \index{chare}chare of type \uw{C} on {\em any}
 116 processor and return a proxy to that chare:}
 117
 118 \begin{alltt}
 119    CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0);
 120 \end{alltt}
 121
 122 \item{This will create a new \index{chare}chare of type \uw{C} on processor
 123 \kw{destPE} and return a proxy to that chare:}
 124
 125 \begin{alltt}
 126    CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0, destPE);
 127 \end{alltt}
 128
 129 \end{enumerate}
 130
 131 For an example of chare creation in a full application, see
 132 \examplerefdir{fib} in the \charmpp software distribution, which
 133 calculates fibonacci numbers in parallel.
 134
 135 \subsection{Method Invocation on Chares}
 136
 137 A message \index{message} may be sent to a \index{chare}chare through a proxy
 138 object using the notation:
 139
 140 \begin{alltt}
 141     chareProxy.EntryMethod(\uw{parameters})
 142 \end{alltt}
 143
 144 This invokes the entry method \uw{EntryMethod} on the chare referred
 145 to by the proxy \uw{chareProxy}. This call
 146 is asynchronous and non-blocking; it returns immediately after sending the
 147 message.
 148
 149
 150 \subsection{Local Access}
 151
 152 You can get direct access to a local chare using the
 153 proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
 154 to the chare if it exists on the local processor, and NULL otherwise.
 155
 156 \begin{alltt}
 157     C *c=chareProxy.ckLocal();
 158     if (c==NULL) {
 159         // object is remote; send message
 160     } else {
 161         // object is local; directly use members and methods of c
 162     }
 163 \end{alltt}
 164