Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / groups.tex
1 So far, we have discussed chares separately from the underlying
2 hardware resources to which they are mapped. However, for writing
3 lower-level libraries or optimizing application performance it is
4 sometimes useful to create chare collections where a single chare is
5 mapped per specified resource used in the run. The
6 \kw{group} \footnote{Originally called {\em Branch Office Chare} or
7   {\em Branched Chare}} and \kw{node group} constructs provide this
8 facility by creating a collection of chares with \index{chare}a single
9 chare (or {\sl branch}) on each PE (in the case of groups) or process
10 (for node groups). 
11
12 \section{Group Objects}
13 \label{sec:group}
14
15 Groups have a definition syntax similar to normal chares, and they
16 have to inherit from the system-defined class
17 \kw{CBase}\_\uw{ClassName}, where \uw{ClassName} is the name of the
18 group's \CC{} class \footnote{Older, deprecated syntax allows groups
19 to inherit directly from the system-defined class \kw{Group}}.
20
21 \subsection{Group Definition}
22
23 In the interface ({\tt .ci}) file, we declare
24
25 \begin{alltt}
26 group Foo \{
27   // Interface specifications as for normal chares
28
29   // For instance, the constructor ...
30   entry Foo(\uw{parameters1});
31
32   // ... and an entry method
33   entry void someEntryMethod(\uw{parameters2});
34 \};
35 \end{alltt}
36
37 The definition of the {\tt Foo} class is given in the \texttt{.h} file, as follows:
38
39 \begin{alltt}
40 class Foo : public CBase\_Foo \{
41   // Data and member functions as in C++
42   // Entry functions as for normal chares
43
44   public:
45     Foo(\uw{parameters1});
46     void someEntryMethod(\uw{parameters2});
47 \};
48 \end{alltt}
49
50 \subsection{Group Creation}
51
52 Groups are created in a manner similar to chares and chare arrays, i.e. 
53 through \kw{ckNew}. Given the declarations and definitions of group {\tt Foo}
54 from above, we can create a group in the following manner:
55
56 \begin{alltt}
57 CkGroupID fooGroupID = CProxy_Foo::ckNew(\uw{parameters1});
58 \end{alltt}
59
60 In the above, \kw{ckNew} returns an object of type \kw{CkGroupID},
61 which is the globally unique identifier of the corresponding instance
62 of the group.  This identifier is common to all of the group's
63 branches and can be obtained in the group's methods by accessing the variable
64 \kw{thisgroup}, which is a public data member of the \kw{Group}
65 superclass.
66
67 A group can also be identified through its proxy, which can be obtained in one of three ways:
68 (a) as the inherited {\tt thisProxy} data member of the class; (b) when creating a group,
69 you can obtain a proxy to it from a call to \kw{ckNew} 
70 as shown below:
71
72 \begin{alltt}
73 CProxy fooProxy = CProxy_Foo::ckNew(\uw{parameters1});
74 \end{alltt}
75
76 or (c) by using a group identifier to create a proxy, as shown below:
77
78 \begin{alltt}
79 // Assume that we have obtained `fooGroupID' as the CkGroupID for the group
80
81 // Obtain a proxy to the group from its group ID
82 CProxy_Foo anotherFooProxy = CProxy_Foo(fooGroupID);
83 \end{alltt}
84
85 It is possible to specify the dependence of group creations using
86 \uw{CkEntryOptions}. For example, in the following code, the creation of group
87 {\tt GroupB} on each PE depends on the creation of {\tt GroupA} on that PE.
88
89 \begin{alltt}
90 // Create GroupA
91 CkGroupID groupAID = CProxy_GroupA::ckNew(\uw{parameters1});
92
93 // Create GroupB. However, for each PE, do this only 
94 // after GroupA has been created on it
95
96 // Specify the dependency through a `CkEntryOptions' object
97 CkEntryOptions opts;
98 opts.setGroupDepID(groupAId);
99
100 // The last argument to `ckNew' is the `CkEntryOptions' object from above
101 CkGroupID groupBID = CProxy_GroupB::ckNew(\uw{parameters2}, opts);
102 \end{alltt}
103
104 %For groups, \kw{thishandle} is the
105 %handle of the particular branch in which the function is executing: it is a
106 %normal chare handle.
107
108 %Groups can be used to implement data-parallel operations easily.  In addition
109 %to sending messages to a particular branch of a group, one can broadcast
110 %messages to all branches of a group.  
111 Note that there can be several instances of each group type.
112 In such a case, each instance has a unique group identifier, and its own set
113 of branches.
114
115 \subsection{Method Invocation on Groups}
116
117 An asynchronous entry method can be invoked on a particular branch of a
118 group through a proxy of that group. If we have a group with a proxy
119 {\tt fooProxy} and we wish to invoke entry method {\tt someEntryMethod} on
120 that branch of the group which resides on PE {\tt somePE}, we would accomplish
121 this with the following syntax:
122
123 \begin{alltt}
124 fooProxy[somePE].someEntryMethod(\uw{parameters});
125 \end{alltt}
126
127 %This sends the given parameters to the \index{branch}branch of
128 %the group referred to by \uw{groupProxy} which is on processor number
129 %\uw{Processor} at the entry method \uw{EntryMethod}, which must be a valid
130 %entry method of that group type. 
131 This call is asynchronous and non-blocking; it returns immediately after sending the message.
132 A message may be broadcast \index{broadcast} to all branches of a group
133 (i.e., to all PEs) using the notation :
134
135 \begin{alltt}
136 fooProxy.anotherEntryMethod(\uw{parameters});
137 \end{alltt}
138
139 This invokes entry method \uw{anotherEntryMethod} with the given \uw{parameters} on 
140 all branches of the group. This call is also asynchronous and non-blocking, and it, too, returns immediately
141 after sending the message.
142
143 Recall that each PE hosts a branch of every instantiated group. 
144 Sequential objects, chares and other groups can gain access to this {\em PE-local}
145 branch using \kw{ckLocalBranch()}:
146
147 \begin{alltt}
148 GroupType *g=groupProxy.ckLocalBranch();
149 \end{alltt}
150
151 This call returns a regular \CC\ pointer to the actual object (not a proxy)
152 referred to by the proxy \uw{groupProxy}.  Once a proxy to the
153 local branch of a group is obtained, that branch can be accessed as a regular
154 \CC\ object.  Its public methods can return values, and its public data is 
155 readily accessible.
156 %Thus a dynamically created \index{chare}chare can invoke a public method of a
157 %group without knowing the PE on which it actually resides. 
158 %the method
159 %executes in the local \index{branch}branch of the group.
160
161 Let us end with an example use-case for groups.
162 %One very nice use of Groups is to reduce the number of messages sent between
163 %processors by collecting the data from all the chares on a single processor
164 Suppose that we have a task-parallel program in which we dynamically spawn
165 new chares. Furthermore, assume that each one of these chares has some data
166 to send to the mainchare.  Instead of creating a separate message for each 
167 chare's data, we create a group. When a particular chare
168 finishes its work, it reports its findings to the local branch of the group.
169 When all the chares on a PE have finished their work, the local branch
170 can send a single message to the main chare.  This reduces the number of messages
171 sent to the mainchare from the number of chares created to the number of processors. 
172
173 For a more concrete example on how to use groups, please refer to
174 \examplerefdir{histogram\_group}. It presents a parallel
175 histogramming operation in which chare array elements funnel their bin counts
176 through a group, instead of contributing directly to a reduction across all
177 chares.
178