doc: update section heading
[charm.git] / 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