baa6d0ede3d88a6f8f76b2dd9bac47ac006ef192
[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 \label{sec:groups/creation}
52
53 Groups are created in a manner similar to chares and chare arrays, i.e. 
54 through \kw{ckNew}. Given the declarations and definitions of group {\tt Foo}
55 from above, we can create a group in the following manner:
56
57 \begin{alltt}
58 CkGroupID fooGroupID = CProxy_Foo::ckNew(\uw{parameters1});
59 \end{alltt}
60
61 In the above, \kw{ckNew} returns an object of type \kw{CkGroupID},
62 which is the globally unique identifier of the corresponding instance
63 of the group.  This identifier is common to all of the group's
64 branches and can be obtained in the group's methods by accessing the variable
65 \kw{thisgroup}, which is a public data member of the \kw{Group}
66 superclass.
67
68 A group can also be identified through its proxy, which can be obtained in one of three ways:
69 (a) as the inherited {\tt thisProxy} data member of the class; (b) when creating a group,
70 you can obtain a proxy to it from a call to \kw{ckNew} 
71 as shown below:
72
73 \begin{alltt}
74 CProxy fooProxy = CProxy_Foo::ckNew(\uw{parameters1});
75 \end{alltt}
76
77 or (c) by using a group identifier to create a proxy, as shown below:
78
79 \begin{alltt}
80 // Assume that we have obtained `fooGroupID' as the CkGroupID for the group
81
82 // Obtain a proxy to the group from its group ID
83 CProxy_Foo anotherFooProxy = CProxy_Foo(fooGroupID);
84 \end{alltt}
85
86 It is possible to specify the dependence of group creations using
87 \uw{CkEntryOptions}. For example, in the following code, the creation of group
88 {\tt GroupB} on each PE depends on the creation of {\tt GroupA} on that PE.
89
90 \begin{alltt}
91 // Create GroupA
92 CkGroupID groupAID = CProxy_GroupA::ckNew(\uw{parameters1});
93
94 // Create GroupB. However, for each PE, do this only 
95 // after GroupA has been created on it
96
97 // Specify the dependency through a `CkEntryOptions' object
98 CkEntryOptions opts;
99 opts.setGroupDepID(groupAId);
100
101 // The last argument to `ckNew' is the `CkEntryOptions' object from above
102 CkGroupID groupBID = CProxy_GroupB::ckNew(\uw{parameters2}, opts);
103 \end{alltt}
104
105 %For groups, \kw{thishandle} is the
106 %handle of the particular branch in which the function is executing: it is a
107 %normal chare handle.
108
109 %Groups can be used to implement data-parallel operations easily.  In addition
110 %to sending messages to a particular branch of a group, one can broadcast
111 %messages to all branches of a group.  
112 Note that there can be several instances of each group type.
113 In such a case, each instance has a unique group identifier, and its own set
114 of branches.
115
116 \subsection{Method Invocation on Groups}
117
118 An asynchronous entry method can be invoked on a particular branch of a
119 group through a proxy of that group. If we have a group with a proxy
120 {\tt fooProxy} and we wish to invoke entry method {\tt someEntryMethod} on
121 that branch of the group which resides on PE {\tt somePE}, we would accomplish
122 this with the following syntax:
123
124 \begin{alltt}
125 fooProxy[somePE].someEntryMethod(\uw{parameters});
126 \end{alltt}
127
128 %This sends the given parameters to the \index{branch}branch of
129 %the group referred to by \uw{groupProxy} which is on processor number
130 %\uw{Processor} at the entry method \uw{EntryMethod}, which must be a valid
131 %entry method of that group type. 
132 This call is asynchronous and non-blocking; it returns immediately after sending the message.
133 A message may be broadcast \index{broadcast} to all branches of a group
134 (i.e., to all PEs) using the notation :
135
136 \begin{alltt}
137 fooProxy.anotherEntryMethod(\uw{parameters});
138 \end{alltt}
139
140 This invokes entry method \uw{anotherEntryMethod} with the given \uw{parameters} on 
141 all branches of the group. This call is also asynchronous and non-blocking, and it, too, returns immediately
142 after sending the message.
143
144 Recall that each PE hosts a branch of every instantiated group. 
145 Sequential objects, chares and other groups can gain access to this {\em PE-local}
146 branch using \kw{ckLocalBranch()}:
147
148 \begin{alltt}
149 GroupType *g=groupProxy.ckLocalBranch();
150 \end{alltt}
151
152 This call returns a regular \CC\ pointer to the actual object (not a proxy)
153 referred to by the proxy \uw{groupProxy}.  Once a proxy to the
154 local branch of a group is obtained, that branch can be accessed as a regular
155 \CC\ object.  Its public methods can return values, and its public data is 
156 readily accessible.
157 %Thus a dynamically created \index{chare}chare can invoke a public method of a
158 %group without knowing the PE on which it actually resides. 
159 %the method
160 %executes in the local \index{branch}branch of the group.
161
162 Let us end with an example use-case for groups.
163 %One very nice use of Groups is to reduce the number of messages sent between
164 %processors by collecting the data from all the chares on a single processor
165 Suppose that we have a task-parallel program in which we dynamically spawn
166 new chares. Furthermore, assume that each one of these chares has some data
167 to send to the mainchare.  Instead of creating a separate message for each 
168 chare's data, we create a group. When a particular chare
169 finishes its work, it reports its findings to the local branch of the group.
170 When all the chares on a PE have finished their work, the local branch
171 can send a single message to the main chare.  This reduces the number of messages
172 sent to the mainchare from the number of chares created to the number of processors. 
173
174 For a more concrete example on how to use groups, please refer to
175 \examplerefdir{histogram\_group}. It presents a parallel
176 histogramming operation in which chare array elements funnel their bin counts
177 through a group, instead of contributing directly to a reduction across all
178 chares.
179