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