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